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Volume 2: The SOS Calls comprises the remaining chapters and the 
appendixes of this manual. The chapter numbers continue the sequence 
of those in Volume 1. 

Volume 2 defines the individual SOS calls. Chapter 9 contains a 
description of each file call; Chapter 10, each device call, Chapter 11, each 
memory call; and Chapter 1 2, each utility call. Each of these chapters is 
divided into two sections: calls, and errors. 

The calls defined in each chapter are arranged In numerical order by call 
number (for example, CREATE is $C0). Each call description contains the 
following information: 

• Definition of the call 

• Required parameters 

• Optional parameters 

• Comments 

• Errors 

The parameter fields are of four types: 

• Pointer (2 bytes): The location of a table or parameter list. 

• Value {1 , 2, or 4 bytes): A parameter passed by the caller to SOS. 

• Resu It ( 1 , 2 , o r 4 by tes ) : A parameter retu rned by SOS to 
the caller. 

• Value/result (1 , 2, or4 bytes): A parameter passed to SOS and 
back to the caller, possibly changed, 

• Unused (any length): Occurs when the same parameter list is 
used by two calls, one of which ignores some parameters in the 
list. An unused field can be of any length. 



Each SOS call has three parts, described in Chapter 8 of Volume 1 

• The call block 

• The required parameter list 

• The optional parameter list 

They can be diagrammed as shown in Figure 0-1: 



BRK = $00 




call^num - $C0 




' value 




pa rm list 




pointer 






parm count = S03 




value 




pathname 




pointer 




OpUon_lrst 




pointer 




length 




value 










file type 






value 




1 












aux type 




2 




value 




3 




Stor type 








value 




4 


f 


EOF 




7 




value 


/ 



Figure 0-1 . Parts of the SOS Gall 



Each call description is accompanied by a diagram like that shown in 
Figure 0-1. Most of the diagrams omit the call block, as these are identical, 
except for the call_num , and show only the required and optional 
parameter lists. In addition, the parm_count {shown in the diagram) is 
omitted from the required parameter list. 

The one exception to this pattern is TERMINATE, for which the call block 
only is shown, as in Figure 0-2, because it differs fronn the standard form. 
See section 12.1.6 for details. 



BRK = $00 






calt_num = $65 

" valve 


pami_Nst ' p 
PQintef 



Figure 0-2. TERMINATE Call Block 
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2 9,1 File Calls 
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9.1 File Calls 



This section contains descriptions of all calls that operate on files. These 
calls operate on closed files and refer to a file by its pathname. 



$C0: 


CREATE 


$C1: 


DESTROY 


$C2: 


RENAME 


$C3; 


SET FILE INFO 


$C4: 


GET FILE INFO 


$C5: 


VOLUME 


$C6: 


SET PREFIX 


$C7: 


GET PREFIX 


$C8: 


OPEN 



These calls operate on access paths to open files and refer to the access 
path by its ref_num, returned by the OPEN call. 



$C9: 


NEWLINE 


$GA: 


READ 


$CB: 


WRITE 


$CC: 


CLOSE 


$CD: 


FLUSH 


$CE: 


SET MARK 


$CF; 


GET MARK 


$D0: 


SET EOF 


$D1: 


GET EOF 


$D2: 


SET LEVEL 


$D3: 


GET LEVEL 
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ai.1 CREATE 



File Call $C0 



This call creates a standard file or 
subdirectory file on a volume mounted 
on a block device. A directory 
entry is established, and at least one 
block is allocated on the volume. 

This call cannot create a volume directory 
or a character file. Volume directories 
are "created" by the formatting 
utility on (he Apple III Utilities disk. 
Character files are "created" by the 
System Configuration Program. 

Required Parameter List 

pathname: pointer 

This parameter is a pointer to a 
string in memory containing the 
pathname of the file to be created: 
the first byte of the string contains 
the number of bytes in the 
pathname; the remaining bytes 
contain the pathname itself. The 
last name in the pathname should 
be that of a file that does not 
currently exist in the specified 
directory, or a DUPERR will result. 



CREATE SC0 



S03 



pathname 

pointer 



opllon_list 

pointer 



length 

value 



filejype 

value 



auxlype 

value 



storage type 
value 



EOF 

value 



option list: pointer 

This is a pointer to the optional parameter list if length (below) is between 
1 and 8; otherwise it is ignored. 



length: 1 byte value 

Range: $0..$08 

This is the length in bytes of the optional parameter list. It specifies which 
optional parameters are supplied. 
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The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take half 
a parameter, but reduces the length to the next defined value. 

= no optional parameters 

1 = filejype 

3 = filejype through aux_type 

4 = f ile_ type through stor_ type 
8 - file_type through EOF 

Optional Parameter List 

tile_type: 1 byte value 

Range: $00..$FF 
Default; $00 

This is the type identifier for this file. The file_type does not affect the 
way in which SOS deals with the file: it is used only by interpreters to 
determine the internal arrangement and meaning of the bytes in the file. 
These values of filejype are now defined: 



'-$03 


= Typeless file (BASIC or Pascal "unknown" file) 


m 


- File containing all bad blocks on the volume 


m 


- Pascal or assembly-language code file 




^ Pascal text file 




= BASIC text file; Pascal ASCII file 


m 


= Pascal data file 


106 


= General binary file 




= Font file 




- Screen image file 


$09 


= Business BASIC program file 


$01^ 


= Business BASIC data file 


W^- 


- Word Processor file 


$0C 


= SOS system file (DRIVER, INTERP, KERNEL) 


$0D, $0E 


= SOS reserved 


$0F 


- Directory file (see storage type) 


$10..$DF 


- SOS reserved 


$E0..$FF 


= ProDOS reserved 
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aux type: 2 byte value 

Range; $00..$FFFF 
Default: $0000 

This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field 
to store the record size of its data files. If the file is a volume directory 
{storage_type is$0F), these bytes contain the total number of blocks on 
the volume. 

storagejype: 1 byte value 

Range: $01..$0D 
Default: $01 

This indicates whether the file is to be a standard file ($01 } or a 
subdirectory file ($0D). All other values are illegal and will result in a 
TYPERR, 

EOF: 4 byte value 

Range: $00000000.. $00FFFFFF 
Default: $00000000 

This specifies the amount of space to preallocate for the file.One data 
block is automatically allocated regardless of the value of EOF; additional 
data blocks are allocated until the number of bytes in the allocated data 
blocks equals or exceeds EOF. In addition to the data blocks, index blocks 
are allocated as necessary. 

The maximum creation size for standard files is $00FFFFFF. or $8000 
blocks. The maximum creation size for subdirectories is $0000FFFF, or 
$80 blocks. The total number of blocks occupied by a file is the number of 
data blocks plus the number of index blocks: see Chapter 5 of Volume 1 
for more information. 

Comments 

The file created must be a block file. The access attribute of the file is 
implicitly set to the following: 

standard file - $E3: (destroy, backup, rename, write, read) 
subdirectory = $E1; (destroy, backup, rename, NO write, read) 
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Errors 






$27: 


lOERR 


I/O error 


$2B: 


NOWRITE 


Volume Is write-protected 


$40: 


BADPATH 


Invalid pathname syntax 


$44: 


PNFERR 


Path not found 


$45: 


VNFERR 


Volume not found 


$46: 


FNFERR 


Subdirectory file not found 


$47: 


DUPERR 


Attempt to CREATE an existing file 


$48: 


OVRERR 


Overrun error. Either EOF too large or not 






enough disk space 


$49: 


DIRFULL 


Directory is full 


$4B: 


TYPERR 


Slorage_lype parameter neither $01 nor $0D 


$52: 


NOTSOS 


Not a SOS volume 


$53: 


BADLSTCNT 


Invalid length parameter 


$58; 


NOTBLKDEV 


Not a block device 



nie Calls and Errcs 



9.1.2 DESTROY 



File Call $C1 



This call deletes the file specified by 
the pathname parameter by 
removing the file's directory entry. 
DESTROY releases alt blocks used 
by ttiat file back to free space on 
that volume. 



DESTROY SCI 



pathname 

poinlef 



2 



The file can be either a standard or 

subdirectory file. Volume 

directories cannot be destroyed except by physical reformatting of the 
medium. Character files are "destroyed" by the System Configuration 
Program. 

Required Parameters 
pattiname: pointer 

This parameter is a pointer to a string containing the pathname of the file 
to be destroyed: the first byte of the string contains the number of bytes in 
the pathname; the remaining bytes contain the pathname itself. 

ComrDents 

A file cannot be destroyed if it is currently open. If the pathname refers to 
a subdirectory file, then that subdirectory must be completely empty in 
order for the subdirectory to be destroyed. 
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Errors 






$27: 


lOERR 


I/O error 


$2B: 


NOWRITE 


Volume is write-protected 


$40: 


BADPATH 


Invalid pathname syntax 


$44: 


PNFERR 


Path not found 


$45: 


VNFERR 


Volume not found 


$46: 


FNFERR 


File not found 


$4A: 


CPTERR 


Incompatible file format 


$4B: 


TYPERR 


Unsupported file storage type 


$4E: 


ACCSERR 


File's access attribute prevents 






DESTROY 


$50; 


FILBUSY 


File is open. Request denied. 


$52: 


NOTSOS 


Not a SOS volume 


$58; 


NOTBLKDEV 


Not a block device 



9.1.3 RENAME 



File Call $C2 



This call changes the name of the 
file specified by the pathname 
parameter to that specified by 
new_pathname. Only block files 
may be renamed; character files are 
"renamed" by the System 
Configuration Program. 



Required Parameters 

pathname; pointer 

This parameter is a pointer to a 
string containing the old pathname of the file to be renamed: the first byte 
of the siring contains the number of bytes in the pathname; the remaining 
bytes contain the pathname itself. The pathname must refer to either a 
volume directory, subdirectory, or standard file. 

new pathname: pointer 

This parameter is a pointer to a string containing the new pathname of the 
file to be renamed: the first byte of the string contains the number of bytes 
in the pathname; the remaining bytes contain the pathname itself. The 
pathname can be either a complete or partial pathname. Only the last 
file name of the new pathname may differ from that in the old pathname, 

Comments 

The file must reside on a block device. Both pathname and 
new_pathname must be identical except for the last file name. For 
example, the path /VOL,1/FILE 1 can be renamed /V0L.1/FILE.2 , but 
not /VOL.2/FILE.Xor A/OL.1/SUBDIR.A/FILE.X . 

A file may not be renamed while it is open for writing. 

If new pathname matches the pathname of an existing file, you will get 
aDUPERR. 







1 



RENAME $C2 



$02 



pathname 

poinler 



new_p3thname 

pointer 
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Errors 

$27: lOERR 

$2B; NOWRITE 

$40: BADPATH 

$44; PNFERR 

$45: VNFERR 

$46: FNFERR 

$47; DUPERR 

$4A: CPTERR 

$4B; TYPERR 

$4E; ACCSERR 

$50; FILBUSY 

$52: NOTSOS 

$57; DUPVOL 

$58: NOTBLKDEV 



I/O error 

Volume is write-protected 

Invalid pathname syntax 

Path not found 

Volume not found 

File not found 

Duplicate file name 

Incompatible file format 

File storage type not supported 

File's access attribute prevents RENAME 

File is open. Request denied. 

Not a SOS volume 

Duplicate volume 

Not a block device 
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9.1.4 SET FILE INFO 



File Call $C3 



This call modifies file information 
in the directory entry of the block 
file specified by the pathname 
parameter. If the file is closed, a 
SET_FILE_INFO call will modify 
the file information immediately. 
This information will be returned 
by any subsequent 
GET_FtLE_INFO calls. If the file 
is open, no file information will be 
modified until the tile is closed. 

Required Parameters 

pathname: pointer 

This parameter is a pointer to a 
string containing the file name of 
the file whose directory entry will 
be modified: the first byte of the 
string contains the number of bytes 
in the pathname; the remaining 
bytes contain the pathname itself. 



SET FILE iNF0$C3 



$03 



pathname 

pointer 



option list 

pointer 



length 

value 



B 
C 
D 

E 



lastmod 

value 



option list: pointer 

This is a pointer to the optional 
parameter list if length is between 
$01 and $0F, otherwise it is ignored, 

length: 1 byte value 

Range: $00..$0F 

This is the length of the optional parameter list. It specifies which optional 
parameters are supplied. If length equals $00, no optional parameters are 
supplied: the call does nothing more than error checking. 



value 



lile_tvpe 

value 



auKjype 

value 



unused 
(7 bytes) 
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The values below tell the number of bytes In a list with complete 
parameters. If SOS receives an intermediate value, it does not take half a 
parameter, but reduces the length to the next defined value, 

= no optional parameters 

1 ~ access 

2 = access through filejype 
4 = access through aux type 
F = access through last mod 

Optional Parameters 

access: 1 byte value 

Range: $00..$E3 
Default: None 

This parameter specifies the access allowed to the file. Bits 4 through 2 
are reserved for future implementation and must be set to 0, otherwise an 
ACCSERR will occur 





r 


D 


RN 


B 


RESERVED 


W 





Write-enable 
Read-enable 



I I — . . Backup 

I Hename-enable 

Destroy-enable 

For bits 7, 6, 1 . and 0, 

- not allowed 

1 = allowed 

These bits may be altered as the user wishes by the S ET_FI LE_IN FO 
call, 
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For bit 5, 

= backup not needed 

1 - backup needed 

This bit is always set when a SET_FILE_1NF0 call is made. Only 
the Backup III program can clear it. 

lilejype: 1 byte value 

Range: $00..$FF 
Default: Current value 

This the type identifier for this file. The filejype does not affect the way in 
which SOS deals with the file: it is used only by interpreters to determine 
the internal arrangement and meaning of the bytes in the file. These values 
of filejype are now defined: 



$00 


Typeless file {BASIC or Pascal "unknown" file) 


$01 


File containing all bad blocks on the volume 


$02 


Pascal or assembly-language code file 


$03 


Pascal text file 


$04 


BASIC text file; Pascal ASCI 1 file 


$05 


Pascal data file 


$06 


General binary file 


$07 


Font file 


$08 


Screen image file 


$09 


Business BASIC program file 


$0A 


Business BASIC data file 


$0B 


Word Processor file 


$0C 


SOS system file (DRIVER, INTERR KERNEL) 


$0D, $0E = 


SOS reserved 


$0F 


Directory file (see storagejype) 


$10..$DF = 


SOS reserved 


$E0..$FF = 


ProDOS reserved 
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aux_type: 2 byte value 

Range: $0000..$FFFF 
Default: Current value 

This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field 
to store the record size of its data files. If the tile is a volume director/ 
(storagejype is $0FJ, these bytes contain the total number of blocks on 
the volume. 

unused: 7 bytes 

These bytes are here to maintain symmetry with GET_FILE_INFO, and 
are always ignored by SET_FILE_INFO. 

last_mod: 4 byte value 

Range: $00000000..$FFFFFFFF 
Default: Current value 

This is the date and time the file was last closed after being written to. It 
can be set to a user-defined value, or you can use the GET_TIME call 
(see the Utility calls) and form this value from the current time. The 
last^mod parameter is organized as two 2-byte words, each stored low 
byte first: 



TBS 


4 3 2 1 


9 




5 4 a s 1 a 


1 1 1 r 1 1 

ynr 

1 1 I 1 1 < 


- 1 11 

1 1 1 


■ r r 1 r 

) 1 1 1 




r 1 


T T 1 
hour 

1 1 1 1 


1 

a a 
1 


1 1 1 1 1 

1 1 _l .1 I 




6yle3 











The ranges for these fields are as follows: 



Year; 





.99 


($00 


.$63) 


Month; 





.12 


($00. 


.S0C) 


Day: 





.31 


(S00. 


.$1F) 


Hour; 





.24 


($00. 


.$18) 


Minute; 





.60 


($00. 


.$3C} 



A zero value for the month or day means thiat no value was set 
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No checking is performed on this parameter. If you use ttie GET_TliVIE 
call, you must pack the 18-byte time parameter from that call into the 
proper format for the SET_FILE INFO call's last^mod parameter. 

Comments 

The default value for all optional parameters that are omitted is the current 
value of that attribute of the file: for example, omitting the last_mod 
parameter results in no change to that file's modification date and time. 

Tine same required and optional parameter lists can be used for 
GET_FILE_INFO In fact, you can perform a 
GET_FILE_INFO, examine and perhaps alter the values in the 
parameter lists, and then perform a SET_FILE_INFO to update 
the file's attributes. 

You can perform SET_FILE INFO on any block file, regardless of the 

current value of its access attribute. In this call, therefore, an access error 
can result only from passing an invalid access parameter 

SET_FILE_INFO affects a file's directory entry only. It does not affect 
the FCB entry for any access path to the file. Specifically, if you open a file 

with read/write access, then use a SET FILE INFO call to change the 

access to read-oniy, you still write to the file via that access path, but you 
cannot open another access path. This is because the access field in the 
file's directory entry will not be updated until the file is closed, and the 
FCB entries will not be updated at all: so, as far as SOS is concerned, this 
is still a read/write file, for which only one access path is allowed. As soon 
as you close the file, however, the new access value will be stored in the 
directory entry, and multiple read-only access paths can be opened. 
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Errors 


$27: 


lOERR 


$2B 


NOWRITE 


$40. 


BADPATH 


$44- 


PNFERR 


$45. 


VNFERR 


$46- 


FNFERR 


$4A 


: CPTERR 


$4B 


: TYPERR 


$4E 


ACCSERR 


$52 


NOTSOS 


$53- 


BADLSTCNT 


$58: 


NOTBLKDEV 



I/O error 

Volume is write-protectecf 
Invalid pathname syntax 
Path not found 
Volunrie not found 
File not found 
Incompatible file format 
Unsupported file storage type 
Access parameter invalid 
Not a SOS volume 
Length parameter invalid 
File is not on a btocl< device 



File Calls and Errors 



17 



9.1.5 GET_FILE_INFO 



File Call $C4 



This call returns file information 
from the directory entry of the 
block file specified by the 
pathname parameter. 

Required Parameters 

pathname; pointer 

This parameter is a pointer to a 
string containing the pathname of 
the file whose directory entry 
information will be returned: the 
first byte of the string contains the 
number of bytes in the pathname; 
the remaining bytes contain the 
pathname itself. 



GET FILE INFO$C4 
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pathname 

pointer 



option Jlsl 

pointer 



length 

value 



auxjype 

result 



slorage_typc 

result 



EOF 

result 



oplionjist: pointer 

This is a pointer to the optional 
parameter list if length is between 
$01 and $0F; otherwise it is ignored. 

length: 1 byte value 

Range: $00., $0F 

This is the length of the optional 
parameter list. If length equals $00, 
no optional parameters are 
returned: the call does nothing 
more than error checking. 

The values below tell the number 
of bytes in a list with complete 
parameters, if SOS receives an 
intermediate value, it does not take 

half a parameter, but reduces the length to the next defined value. 



access 

result 



file^type 

result 



blocksused 

resijlt 



last mod 

result 
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$00 - no optional parameters 

$01 access 

$02 = access through 

$04 = access through 

$05 = access througn 

$09 = access through 

$0B = access through 

$0F = access through 

Optional Parameters 

access: 1 byte result 

Range; $00,.$C3 

This parameter returns the access allowed to the file. Bits 4 through 2 are 
reserved for future Implementation and are now set to 0. 

I Write-enable 

^ Read-enable 



D 


RN 


B 


RESERVED 


W 


R 






1 





Backup 

Rename-enable 
Destroy-enable 



For bits 7, 6, 1 , and 0, 

= not allowed 

1 = allowed 

For bit 5. 

= backup not needed 

1 = backup needed 

filejype; 1 byte result 

Range: $00..$FF 



fiietype 
auxtype 
storagetype 
EOF 

blocks used 
last mod 



This the type identifier for this file. The filejype does not affect the way in 
which SOS deals with the file: it is used only by interpreters to determine 
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the internal arrangement and meaning of the bytes in the file. These 
values of filejype are now defined: 







Tunp|ip*i*i flip /RA^ir^ nr F^csr^l *nlf nnvA/n*' filp\ 


1 




Pilp pnntaininn h?iri hlnf^k*? nn +hp \/nli imp 
f lit:; Lruf 1 LQiT iiT 1^ an uc«u k/i U\^r\o uii lii?vi_'iljiiic 






1 aoLidi uf Gooci iiuiy icii lyuoyc uu'Uc iiic^ 






Pa^p^il tpyt flip 






BA'^in tpxt filp Pasral ARCi 1 flip 






P;^^rril data filp 






r^onprsl Kina r\y f 1 lp 

l^cTMCICtl L/IMCli y NIC 


if*'* 




Foni f ilo 
1 UF 11 [ lit? 


m 




Screen image file 


$09 




Business BASIC program file 


$0B 




V\brd Processor file 


$0C 




SOS system file {DRIVER. INTERP, KERNEL) 


mo, $0E 




SOS reserved 


$0F 




Directory file (see storage type) 


$10..$DF 




SOS reserved 


$E0.,$FF 




ProDOS reserved 



aux^type: 2 byte result 

Range: $0000..$FFFF 

This is the auxiliary file identifier. It is used by interpreters to store any 
additional information about the file. BASIC, for example, uses this field 
to store the record size of its data files. If the file is a volume directory 
(slorage^type is $0F), these bytes contain the total number of blocks 
on the volume. 

storage type: 1 byte result 

Range: $01 ..$03, $0D, $0F 

This byte describes the external format of the file: how the blocks that 
compose the file are stored on the volume, 

$01 = seedling file ( <=EOF<=5l2 bytes) 
$02 = sapling file ( 512 EOF <= 1 28K bytes) 

$03= tree file (128K < EOF < 16M bytes) 

$00 = subdirectory file 
$0F - volume directory file 
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These structures are fully explained in Chapter 5. In brief, seedling files 
are stored as one data block, sapling files are stored as one index block 
and up to 256 data blocks; tree files are stored as one root index block, 
up to 127 subindex blocks, and up to 32,767 data blocks. Directories and 
subdirectories do not use index blocks, and instead are stored as doubly- 
linked lists of blocks. 



EOF: 4 byte result 

Range: $00000000.. $00FFFFFF 

This is the position of the end of file marker. It Indicates the number 
of bytes readable from the file. This is the EOF value stored in the file's 
directory entry when the file was created or last closed. It is accurate 
only if the file is not open for wnting. If the file is open for writing, the 
current EOF (stored in the file's FCB entry) can be read by the 
GET_EOF call. 

blocks used: 2 byte result 

Range: $0000..$FFFF 

If the file is a standard file or subdirectory (storage_type is $01 , $02, $03, 
or$0D), blocl(s_u5ed is the total number of blocks (including index 
blocks) currently used by the file. 

If the file is a sparse file, the blocks used value can be 
substantially less than one would expect from the EOF. 

If the file is a volume directory (storage_type is $0F), blocks_used is the 
total number of blocks used by all files on the volume. 

last_mod: 4 byte result 

Range: $00000000.. $FFFFFFFF 

This is the date and time the file was last closed after being written to. If 
the file has never been written to, these bytes are the same as the creation 
date of the file. SET FILE INFO can also change the modification date. 










7 B S 1 3 Z > 


B ] ? e s 




1 I I 1 1 1 


-T 1 i - 


1 1 1 I 
day 


1 [ I 1 1 1 


1 1 1. 


.lilt 



1( 1 1 



e e e 

] L 



_L_ 
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The ranges for these fields are as follows; 



Year: 


0. 


.99 


($00. 


.$63) 


Month: 


0. 


.12 


($00. 


.$0C) 


Day: 


0. 


.31 


($00. 


.$1F) 


Hour: 


0. 


.24 


($00. 


.$18) 


Minute: 


0, 


-60 


($00. 


.$3C) 



A zero value for the month or day means that no value was set. 
Comments 

This call can be performed when the file is either open or closed. 
The same required and optional parameter lists can be used for 
SET_FILE_INFO. A GET_FILE_INFO call to an open file will return 
file information from the directory entry, not access path information from 
the FCB entry. This is not surprising, since the GET_FILE_INFO call 
refers to a file by its pattiname, not its ref_num. For example, if you have 
changed the EOF since the file was opened, GET_FILE_INFO will not 
return the current value. 



Errors 



$27: 


lOERR 


I/O error 


$40: 


BAD PATH 


Invalid pathname syntax 


$44: 


PNFERR 


Path not found 


$45: 


VNFERR 


Volume not found 


$46: 


FNFERR 


File not found 


$4A: 


CPTERR 


Incompatible file format 


$4B: 


TYPERR 


Unsupported file storage type 


$52: 


NOTSOS 


Not a SOS volume 


$53: 


BADLSTCNT 


Length parameter invalid 


$58: 


NOTBLKDEV 


Not a block device 
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9.1.6 VOLUME 



File Calf $C5 



When given the name of a device, 
this call returns the volume name i 
the volume contained In that 
device, the number of blocks on 
that volumG, and the number of 
currently unallocated blocks on 
that volume. 



Required Parameters 
dev name; pointer 



This parameter is a pointer to a 
string containing the device name: 
the first byte of the string contains 
the number of bytes in the device 
name; the remaining bytes contain 
the device name itself. 



volname: pointer 

This is a pointer to a buffer at least $10 bytes long into which the vofume 
name w^ill be returned: the first byte in the buffer contains the number of 
bytes in the volume name; the rest contain the name itself. 

total_blocks: 2 byte result 

Range: $0000.. $FFFF 

This is the total number of blocks contained by the volume in the 
specified block device. 

free_blocks: 2 byte result 

Range; $000i3..$FFFF 

This is the number of unallocated blocks contained by the volume in the 
specified block device. 

Comments 

The dev_name must point to the name of a block device. 



VOLUME 5C5 



>f 



$04 



dev, name 

pointer 



pointer 



(otal.blocks 

result 



tree.blocks 

result 
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Cn Ur O 






13) w. 




UcViOG nui luunu 


$27: 


lOERR 


I/O error 


$45: 


VNFERR 


Volume not found 


$4A: 


CPTERR 


Incompatible file format 


$52: 


NOTSOS 


Not a SOS volume 


$58: 


NOTBLKDEV 


Not a block device 
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File Call $C6 



SET PREFIX $C6 



9.1.7 SET„PREFIX 

This call sets the current SOS 
prefix pathname to that specified by 
pathname. 

Required Parameters 

pathname: pointer 

This parameter is a pointer to a string containing the pathname that will 
replace the current prefix pathname: the first byte of the string contains 
the number of bytes in the pathname; the remaining bytes contain the 
pathname itself. This pathname specifies a volume directory or 
subdirectory, not a character file or a standard file. 




Comments 



The system prefix is appended to the beginning of any pathname not 
beginning in a volume name or device name: a volume name is preceded 
by a slash, and a device name begins with a period. 

If the new prefix begins with a volume name, only syntax checking is 
performed on it: SOS does not verify that the directory file specified by 
the prefix is actually on line. If the new prefix begins with a device name, 
SOS substitutes the corresponding volume name: the SOS prefix always 
begins with a volume name. 

The prefix can be reset to null by passing a pathname with a length of 
zero characters. 

Upon system boot, the prefix is initialized to the volume directory name of 
the boot disk. 

^} The pathnmne can optionally terminate with a 
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Errors 

$27: lOERR 

$40: BADPATH 

$58: NOTBLKDEV 



[/O error 

Invalid pathname syntax 
Not a block device 
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9.1.8 GET_PREFIX File Call $C7 

This call returns the current SOS get_prefix $C7 

prefix pathname. 



Required Parameters 

pathname: pointer 

This parameter is a pointer to a 
string into which SOS is to store 
the current prefix pathname: the 
first byte of the string contains 
the numtier of bytes in the prefix 
prefix itself. 

length: 1 byte value 

Range: $00..$FF 
Default: $80 

This is the maximum number of bytes in the pathname buffer This should 
be set as long as the longest prefix the interpreter accepts: SOS will 
accept up to 128 ($80) bytes. A BTSERR is returned if the pathname is 
longer than length. 

Commerjts 

If the SOS prefix pathname has been set to the null string (no prefix), the 
null string is returned. 

If the prefix pathname is not null, it is terminated with a slash. 

If the first name in the prefix pathname is a volume name, the pathname 
begins with a slash. 

Errors 




the remaining bytes contain the 



$4F: BTSERR Buffer too small 
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9.1.9 OPEN 

This call causes SOS to open an 
access path (allowing read-access, 
write-access. or both) to the file 
specified by pathname. For this 
access path, SOS makes an entry in 
the file control block and allocates a 
1024-byte I/O buffer. This buffer 
holds the contents of one index 
block (if the file has any) and one 
data block. 

Required Parameters 

pathname: pointer 

This is a pointer to a string in 
memory containing the pathname 
of the file to be opened: the first 
byte is the number of characters in 
the pathname; the remaining byles 
are the characters of the pathname 
itself. It may be any block or 
character file. 

ref_num: 1 byte result 

Range: $01. .$10, $81. .$90 



File Call $C8 



OPEN $C8 






$04 




I 


pathname 






pointer 




2 






3 


ret num 






result 




4 








optfonjist 






pointer 




5 




S 


lenglti 






value 











req access 




value 




1 


pages 






value 




2 


io_ buffer 






poinler 




3 







The reference number is assigned when an access path to a file is 
opened. It uniquely identifies an access path to the file: any open-file call 
will operate on a single access path, not the file itself. 

optionjist: pointer 

This points to optional parameter list if length is between $01 and $04; 
otherwise it is ignored. 
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tength: 1 byte value 

Range: $00.. $04 

This is the tength in bytes of the optional parameter list. It specifies which 
optional parameters are supplied. 

The values below tell the number of bytes in a list with complete 
parameters. If SOS receives an intermediate value, it does not take half a 
parameter, but reduces the length to the next defined value. 

$00 = no optional parameters 
$01 - req access 

$04 = req_access through io_ buffer 

Optional Parameters 

req_acces5: 1 byte value 

Range: $00..$03 
Default; $00 

This is the requested file access. SOS compares this parameter with the 
file's current access-attribute byte to ensure that the intended file 
operations are permitted, A $00 requests as much access as permitted, 

$00 = Open as permitted 

$01 = Open for reading only 

$02 = Open forwriting only 

$03 = Open for reading and writing 

A standard file that is already open for wriHng may have only one access 
path: a req_acces$ of $00 will open the existing access path for reading as 
well. A standard file on a w rite-protected volume may never be opened 
for writing; a req^access of $00 wil( open such a file for reading only. 

A character file may have multiple access paths with read-access, write- 
access, or both, if the file's device allows such access. 
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pages; 1 byte value 

Range: $00 or $04 
Default; $00 

This is the length in 256-byte pages of a caller-supplied I/O buffer, If equal 
to $00, then SOS finds its own buffer, ignoring the io_buffer parameter 
below If equal to $04, then SOS will use the 1024-byte buffer pointed to by 
io buffer. Any value except $00 or $04 is invalid. 

If pages is nonzero, you must specify an io_buffer parameter. 



io_buffer pointer 

This is an indirect pointer to a caller-supplied I/O buffer if and only if the 
pages parameter is nonzero. 



Comments 

On block files, multiple access paths for read-access are permitted. 

On block files, only one access path for writing is permitted: no 
other access path, even for reading only, is permitted at the same time. 

Multiple access paths on character files for both read- and write-access 
are permitted, 

OPEN sets the file level of the opened file to the current system file level 
(see SET_LEVEL and GET_LEVEL), Unless the file level is raised, a 
subsequent CLOSE or FLUSH of multiple files will close or flush this file. 




In general, it is preferable to let SOS allocate an I/O buffer. 



The option_Ust and length parameters are ignored when OPENing 
character files; no optional parameters are used. 
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Errors 




$27: 


lOERR 


$40: 


BADPATH 


$41: 


CFCBFULL 


$42: 


FCBFULL 


$44: 


PNFERR 


$45: 


VNFERR 


$46: 


FNFERR 


$4A: 


OrTERR 


$4b. 


TYHtRR 


$4E; 


ACGSERR 


$4F; 


BTSERR 


$50; 


FILBUSY 


ltd' 
$5*!. 


pJU 1 oUo 


$53: 


BADLSTCNT 


$54: 


OUTOFMEM 


$55: 


BUFTBLFULL 


$56: 


BADSYSBUF 


$57: 


DUPVOL 



I/O error 

Invalid pathname syntax 
Character File Control Block tableful) 
Block File Control Block table full 
Path not found 
Volume not found 
File not found 
Incompatible file format 
Unsupported file storage type 
File doesn't allow this req_acces& 
User-supplied buffer too small 
Can't open for multiple writes 
Not a SOS diskette 
Length parameter invalid 
Out of free memory for buffer 
Buffer table full 

Invalid system buffer parameter 
Duplicate volume 
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9.1.10 NEWLINE File Call $C9 

This call allows the caller to turn 
newline read mode on or off. Once 
newline mode has been fumed on, 
any subsequent READ operation 
will immediately terminate if the 
newline character is encountered in 
tine input byte stream. 



Required Parameters 

ref num; 1 byte value 

Range: $01.. $10. $81 -.$90 

This is the reference number of the access path, provided by the 
OPEN call. 

is_ newline: 1 byte value 

Range: $00.. IFF 

The high bit of this byte determines whether newline read mode is on or 
off. If it is set (is_newHne > $7F), newline mode is on; otherwise, newline 
mode is off. 

newline_char: 1 byte value 

Range: $00..$FF 

This byte indicates the character used to terminate read requests. If 
newline read mode is off, this parameter is ignored. 



NEWLINE $C9 

$03 

ref_nurn 

value 

2 Is newline 

3 



newllne_char 

value 
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Comments 

The newline_char byte need not have any ASCII Interpretation. 

A NEWLINE call to a character file implicitly does a D_CONTROL call 
number 2 (set newline mode) to the device driver represented by that file. 
This changes the newline mode of all access paths to that character file. 



Errors 



$43: BADREFNUM Bad reference number 
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9.1.11 READ File Call $CA 

This call attempts to transfer 
retpjest_count bytes, starting from 
the current file position (mark), 
from the I/O buffer of the file access 
path specified by ref_num into the 
interpreter's data buffer pointed to 
by data_buffer. If newline read 
mode is enabled and the newline 
character is encountered before 
request count bytes have been 
read, then the transfer count 
parameter will be less than 
request_count and exactly equal to 
the number of bytes transferred, 
including the newline byte. 

Required Parameters 

rel_niim: 1 byte value 

Range: $01. .$10, $81 ..$90 

This is the reference number of the access path to be read from, obtained 
through an OPEN call. 

data_buffer pointer 

This is a pointer to the first byte of a caller-supplied buffer at least 
request count bytes long . 

reqtie5l_count: 2 byte value 

Range: $0000..$FFFF 

This is the number of bytes SOS is to read from the file into the buffer If 
request_count equals $0000, the READ call does error checiting only: no 
bytes are read. 



READ $CA 



$04 



1 ref^num 

value 



2 

3 
4 

6 

7 



data buffer 

pointer 



requestcount 

value 



transter_count 

result 
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transfer count: 2 byte result 

Range: $0000..request_count 

If a READ is successful, the number of bytes transferred to the data buffer 
IS returned in this parameter. If a READ is completely unsuccessful, 
transfercount equals $0000. 

Comments 

READ advances the current file position (mark) by one byte for each byte 
transferred. It will advance the mark up to the end-of-file (EOF) marker, 
which points one byte past the last byte in the file. READ fails with an 
EOFERR if and only if the mark already equais EOF; in this case, no bytes 
are transferred and transfer_count returns zero. 

tf a READ operation spans several contiguous blocks on a disk, SOS 
transfers whole blocks directly to the interpreter's data buffer, bypassing 
the I/O buffer; partial blocks go through the I/O buffer. This optimization 
improves performance, but is otherwise invisible to the interpreter writer 
and user. 



Errors 



$27: 
$43: 
$4C: 
$4E: 



lOERR 

BADREFNUM 

EOFERR 

ACCSERR 



I/O error 

Invalid reference number 

End of file has been encountered 

File not open for READing 
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9.1.12 WRITE File Call $CB 

This call attempts to transfer 
request_count bytes, starting from 
the current file position (mark), 
from the buffer pointed to by 
data_buffer to the open file 
specified by ref_num. 

Required Parameters 



ref num: 1 byte value 

Range: $01..$10, $81.-3 

This is the reference number of 
file to be written to, obtained by 
OPEN call, 

data biiffer: pointer 

This is a pointer to a caller-supplies buffer from which SOS is to draw the 
bytes to be written to the file. This pointer is not modified by SOS. 

request count: 2 byte vaiue 

Range: $0000..$FFFF 

This is the number of bytes to be written to the file. 
Comments 

If WRITE ends with an OVRERR, it has written all the bytes that it can to 
the file: it will not tell you how many it has written. Otherwise, WRITE 
always succeeds or fails completely. 

Bytes written to a file may be stored in an I/O buffer, and sent a 
buffer-load at a time. For biock files, WRITE physically alters the bytes on 
the volume only when a block of bytes has been written to the file: this 
occurs automatically when the mark crosses a block boundary. To ensure 
that information in the buffer has been updated on the volume, use the 
FLUSH call. 



WRITE $CB 



$03 



refnum 

vatue 



data _ buffer 

pointer 



3 

B 
1 



requestcount 

value 
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Errors 

$27: tOERR 

$2B; NOWRITE 

$43: BADREFNUM 

$48: OVRERR 

$4E: ACCSERR 



I/O error 

Volume write-protected 

Invalid reference number 

Not enough room in file or on volume 

Tried to write to read-only file 
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9,1.13 CLOSE File Call $CC 

The file access path specified by close $CC 

ref_num is closed. Its file control 
block (FOB) entry is deleted, and if 
the file is a block file that has been 
written to, its I/O buffer is written i 
to the file. The directory entry of a 
block file is then updated from the 
FCB entry. Further file operations using that ref_num will fail. 

Required Parameters 

rel_num: 1 byte value 

Range: $00..$10, $81 ..$90 

This is the reference number of the file to be closed, obtained by an 
OPEN call. 

Comments 

If a block file has been written to, a CLOSE call changes the modification 
date and time of the file to the current date and time. 

If rel num equals $00, all open files are closed whose file level (see 
SET_LEVEL, GET_LEVEL) is greater than or equal to the current 
system level. 

If an error occurs while closing multiple files, all files that can be closed 
will be, and CLOSE will return the error number of the last error that 
occurred. CLOSE will not tell you which files were closed and which 
were not 



$01 



refnum 

value 
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Errors 

$27; lOERR I/O error 

$2B: NOWRITE Volume is write-protected 

$43: BADREFNUM Invalid reference number 

$48: OVRERR Not enough room on volume 
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9.1.14 FLUSH 



File Call $CD 



f a previous WRITE call has left 



FLUSH SCD 



any data in a block file's I/O buffer, 
the FLUSH call wntes these data to 
the volume the file is stored on and 
clears the buffer. If the I/O buffer is 



retnum 

value 



empty, FLUSH simply returns an 

error code of $00. 

Required Parameters 

re(_nuin: 1 byte value 

Range: $00. ,$10 

This is the reference number of the block file access path to be FLUSHed, 
obained from an OPEN call. Since the file is open for writing, this access 
path is the only one. 

Commertts 

FLUSH must be used only on block file access paths that are open 
for writing. 

If the ref_num equals $00, all open files are FLUSHed whose file level (see 
SET_LEVEL. GET_LE\/EL> is greater than or equal to the current 
system file level. 



FLUSH is a time-consuming call: if it is used when not needed, 
performance will suffer. 
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Errors 

$27: lOERR 

$2B: NOWRITE 

$43: BADREFNUM 

$48: OVRERR 

S58: NOTBLKDEV 



I/O error 

Volume is write-protected 
Invalid reference number 
Not enough room on volume 
Not a block device 
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9.1.15 SET_MARK 

This call changes the current file 
position (mark) of the file access 
path specified by ref_num. The 
mark can be changed to an 
absolute byte position in the file, or 
to a position relative to the EOF or 
the current mark. 

Required Parameters 

ref_num; 1 byte value 

Range: $01. .$10 

This is the reference number of the 
block fife access path whose mark 
is to be moved, obtained through 
an OPEN call. 

base: 1 byte value 

Range: $00.. $03 



File Call$CE 

SET MARK$Ce 



$03 



relnum 

value 



base 

value 



3 

^ displacement 
value 

5 
6 



This is the starting byte position in the file from which to calculate the 
new mark position. 

$00 = Absolute, byte $00000000,. $00FFFFFF 

$01 - Backward from EOF 

$02 = Forward from current mark 

$03 = Backward from current mark 

displacement: 4 byte value 

Range: $00000000., $00FFFFFF 

This is the number of bytes the mark is to move from the starting location 
specified by the base parameter. The final computed position must lie 
between $0 and the current EOF ($0 mark <^ EOF $FFFFFF). 
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Errors 

$27: 10 ERR 

$43; BADREFNUM 

$4D: POSNERR 

$58: NOTBLKDEV 



I/O error 

Invalid reference number 
Position out of range 
Not a block device 



F 1 6 Calls and Enors 45 




9.1.16 GET_MARK 

This call returns the current file 
position (mark) of the block file 
access path specified by ref_num. 

Required Parameters 

ref_num1: 1 byte value 

Range: $01. .$10 

This is the reference number of the 
file whose current position is to be 
returned. 

mark: 4 byte result 

Range: $00000000 through 
current EOF value 



File Call $CF 

GET MARKSCF 




This is the current mark position in the file. 



Errors 



$43: BADREFNUIVI Invalid reference number 
$58: NOTBLKDEV Not a block device 
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File Call $D0 

SET EOF $D0 



$03 



ret_num 

value 



base 
value 



9.1.17 SET_EOF 

This call changes the end-of-file 
marker (EOF) of the block file 
whose access path is specified by 
ref num. The EOF can be changed 
to an absolute byte position, or to a 
position relative to the current EOF 
or the current mark. 

If the new EOF is less than the 
current EOF, empty blocks at the 
end of the file are released to the 
system and their data are lost. If 
the new EOF is greater than the 
current EOF, blocks are not 
physically allocated for unwritten 
data. (This is one way of creating a sparse file.) If a program attempts to 
read from these newly created logical positions before they have been 
physically written to, SOS supplies a null ($00) for each byte requested. 



displacemenl 

value 



Required Parameters 

ref_niinfi: 1 byte value 

Range: $01.$ 10 

This is the reference number of the file whose EOF is to be changed, 
returned by an OPEN call. It must refer to a block file open for writing, and 
is thus the file's sole rel num. 
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base: 1 byte vafue 

Range: $00..$03 

This is the position in the file from which to calculate the new value of 
EOF, (the current number of bytes in the file). 

$00 = Absolute, byte $000000.. SFFFFFF 
$01 = Backward from current EOF 
$02 = Forward from current mark position 
$03 - Backward from current mark position 

displacement; 4 byte value 

Range: $00000000,, $00FFFFFF 

This is the number of bytes the EOF is to move from the starting position 
specified in the base parameter. The final computed position must be 
greater than or equal to $000000, and less than or equal to SFFFFFF. 

Comments 

The file must be a block file currently open for writing. Since such a file 
can have only one access path, the ref num specifies the file, as well as 
the access path. 

This call updates the EOF field in the file control block entry, but not the 
EOF field in the file's directory entry: the latter is updated only when the 
access path is closed. For this reason, a GET_FILE_INFO call to an 
open file will not always return the current EOF, A GET EOF call will. 



Errors 




$27: 


lOERR 


I/O error 


$28: 


NOWRITE 


Volume write-protected 


$43: 


BADREFNUM 


Invalid reference number 


$4D: 


POSNERR 


Position out of range 


$4E: 


ACCSERR 


Tried to move EOF of read-only fife 


$58: 


NOTBLKDEV 


Not a block device 




9.1.18 GET_EOF 



File Call $D1 



This returns the current end-of-file 
(EOF) position of the file specified 
by ref_num. 



GET EOF$D1 



Required Parameters 



rel_nurn 



2 



ref_num: 1 byte value 

Range: $01. .$10 



3 



EOF 

result 



This is the reference number of the 
file whose current position is to be 
returned, provided by an OPEN call. 



EOF: 4 byte result 

Range: $00000000.. $00 FFFFFF 

This is the number of bytes that can be read from the file. 
Errors 

$43: BADREFNUM Invalid reference number 
$58: NOTBLKDEV Not a block device 
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Fite Calls aix) Errors 


SI 


9.1.19 SET_LEVEL 




File Call $D2 


This call changes the current value 
of the system file level. All 
subsequent OPENs will assign this 
level to the files opened. All 
subsequent CLOSE and FLUSH 
operations on multiple files (using 




SET_L£V£L $D2 






$01 




1 


level 

value 





a ref num of $00) will operate on 

only those files that were opened with a level greater than or equal to the 
new level. 

Required Parameters 

level: 1 byte value 

Range: $01 ,,$03 

This specifies the new file level. 
Comments 

The system file level is set to $01 at boot time. 
Errors 

$59: LEVLERR Invalid file level 
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9.1.20 GET LEVEL 



File Call $D3 



This call returns the current value 
of the system file level. See 
SET_LEVEL, OPEN, CLOSE, and 
FLUSH. 

Required Parameters 

level; 1 byte result 
Range: $01. .$03 

This parameter returns the current file level. 



GET LEVEL $D3 



$01 



level 

resul! 



Commerjts 

The file level is set to $01 at boot time. 



9.2 File Call Errors 



These error messages can be generated by SOS file calls; in addition, 
some of these calls may generate device call errors, described in section 
10.2. Other errors are listed in Appendix D. 

$40: Invalid pathname syntax (BADPATH) 

The pathname violates the syntax rules in Chapter 4 of Volume 1 . 

$41: Character File Control Block full {CFCBFULL} 

The Character File Control Block (CFC6) table can contain a maximum 
of $10 entries. Opening the same character file more than once will return 
the same ref_nuni (that is, will not consume an additional entry). 
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$42: Block File or Volume Control Block full (FCBFULL) 

The Block File Control Block (BFCB) table can contain a maximum of 
$10 entries. The Volume Control Block (VCB) table can contain a 
maximum of $08 entries. Opening the same block file more than than 
once returns a different ref_rvum and consumes a new entry in the BFCB 
table. Every volume with an open file on tt, whether it is mounted on a 
device or not, consumes one entry in the VCB table. 

$43: Invalid reference number (BADREFNUM) 

The rel_num input parameter does not match the ref_num of any currently 
open file. This error is also returned if the currently open file is marked 
with a bad storage_type; only $01 through $04, $0D, and $0F are allowed. 

$44: Path not found (PNFERR) 

Some file name in the pathname refers to a nonexistent file. The 
pathname's syntax is legal, 

$45: Volume not found (VNFERR) 

The volume name in the pathname refers to a nonexistent volume 
directory. The pathname's syntax Is legal. 

$46: File not found (FNFERR) 

The last file name In the pathname refers to a nonexistent file. The 
pathname's syntax is legal. Note that a missing volume directory file 
returns VNFERR instead of FNFERR, 

$47: Duplicate file name (DUPERR) 

An attempt was made to CREATE a file using a pathname that already 
belongs to a file, or a RENAME was attempted using a new_pathname 
that already belongs to a file. 

$48: Overrun on volume (OVRERR) 

An attempt to allocate blocks on a volume during a CREATE or WRITE 
operation failed due to lack of space on the volume. Tfiis error also is 
returned on an invalid EOF parameter 
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$49: Directory full (DIRFULL) 

No more entries are left in the root/subdirectory. Thus no more files can 
be added (CREATEd) in this directory until another file is DESTROYed. 

$4A; Incompatible file format (CPTERR) 

The file is not backward compatible with this version of SOS. 

$4B: Unsupported storage type (TYPERR) 

The CREATE call accepts only two values for the storage type parameter. 
$01 {standard file) or $0D (subdirectory file). 

$4C: End of (He would be exceeded (EOFERR) 

A READ call was attempted when the mark was equal to the EOF. 

$40: Position out of range (POSNERR) 

A base/displacement parameter pair produced an invalid mark or EOF. 
$4E: Access not allowed (ACCSERR) 

The user attempted to access {RENAME, DESTROY READ from, or 
WRITE to) a file in a way not allowed by its access attribute. 

$4F: Buffer too small (BTSERR) 

The user supplied a buffer too small for its purpose, 

$50: File busy (FILBUSY) 

An attempt was made to RENAME or DESTROY an open file or to OPEN 
a block file already open for writing. 

$51: Directory error (DIRERR) 

The directory entry count disagrees with the actual number of entries in 
the directory file. 

$52: Not a SOS volume (NOTSOS) 

The volume (n the block device contains a directory that is not in SOS 
foriTiat: it may be an Apple II Pascal or DOS 3.3 volume, 
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$53: Length parameter invalid (BADLSTCNT) 

The length supplied for the optional parameter list is invalid. 

$54: Out of memory (OUTOFMEM) 

There is not enough free memory for the SOS system buffer. The user 
must release some memory to SOS to allow the system to use it. 

$55: BuHer Table full (BUFTBLFULL) 

The Buffer Table can contain a maximum of $10 entries. 

$56: Invalid system buffer parameter (BADSYSBUF) 

The buffer pointer parameter must be an extended indirect pointer. 

$57: Duplicate volume (DUPVOLJ 

A SOS call asked SOS to bnng a volume on-line on a particular block 
device. The request was denied because a volume with the same name on 
another bloclt device Is currently on line and contains a currently open 
fit©. 

$58: Not a block device (NOTBLKDEV) 

Only OPEN, NEWLINE, READ, WRITE, and CLOSE file calls can 
reference a character file. For example, CREATE is not permitted on the 
character file .PRINTER. 

$59: Invalid level (LVLERR) 

The SET_LEVEL call received a parameter less than $01 or greater than 
$03. 

$5A: Invalid bit map address (BITMAPADR) 

An index block contained a block number that, according to the bit map, 
is not physically available on the volume: usually this indicates that the 
blocks on the volume have been scrambled. 
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to. 1 Device CaHs 



These SOS calls operate directly on devices. 

$82: D_STATUS 
$83: DECONTROL 
$84: GET_DEV_NUM 
$85: D INFO 
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10.1.1 D_STATUS Device Call $82 

This call returns status information 
about a particular device. The 
information can be either general 
or device-specific information. 
D_STATUS returns information 
about the internal status of 
tlie device or its driver; 
GET_DEV_tNFO returns 
information aboutthe external status 
of the driver and its interface 
with SOS. 



Required Parameters 

dev_num; 1 byte value 

Range: $01. .$18 

This is tlie device number of the device from which to read status 
information, obtained from the GET_DEV_NUiVI call. Each device in the 
system has a unique device number assigned to it when the system is 
booted. Device numbers do not change unless the SOS. DRIVER file is 
Changed and the system is rebooted. 

stalus_code; 1 byte value 

Range: $00..$FF 

This is the number of the status request being made. All device drivers 
respond to the following requests: 

Block devices only: 

$00 Return driver's status byte 
Character devices only: 

$00 No effect 

$01 Return driver's control block 
$02 Return newline status 



D STATUS $82 






$03 




1 


devnum 

value 




2 


statuacode 

value 




3 


status lis) 

pointer 




<f 
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Device drivers afso may respond to other status codes. The complete list 
of status requests available for a device driver is included in the 
documentation accompanying that driver. 

statu s_ list: pointer 

This is a pointer to the buffer in which the device driver returns its status. 
For the three requests above, the buffer is in one of these three formats: 



Bit 



BSV 





\ 


1 


1 

1 


WPR 






device 

write-protected 

device 
busy 



Bit Meaning 

BSY If 1. device Is busy 

WPR m.deviceormediumiswrite-protected 



Figure 10-1. Block Device Status Request $00 



length 

value 




status 
list 

(values) 





Figure 10-2. Character Device Status Request $01 



The status list for each driver has a different format. See tfie manual 
describing that driver 
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is newline 

value 

newlinechar 

value 



Figure 10-3. Character Device Status Request $02 

The newline character is caNed the termination character in the Apple III 
Standard Device Drivers Manual. 

Each driver that defines its own additional status requests also defines 
buffer formats for those requests; see the manual describing that driver. 

Comments 

The length of the buffer pointed to by statusjist must vary depending 
upon the particular status request being made. 



Errors 

$11: BADNUM 

$21: CTLCODE 

$23: NOTOPEN 

$25: NORESRC 
$30..$3F 



Invalid device number 
Invalid status code 
Character device not open 
Resource not available 
Device-specific error 
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E 
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10,1.2 D CONTROL 



Device Call $83 



This call sends control information 
to a particular device. The 
information can be either general 
or device-specific information. 
D_CONTROL operates on 
character devices only. 



D CONTROL S63 







devnum 

value 



control_coiie 

value 



Required Parameters 



3 



control list 
pointer 



dev_num: 1 byte value 4 

Range: $01. .$18 I 

This is the device number of the device to wl^ich to send control 
information, obtained from the GET_DEV_NUIVI call, Each device in the 
system has a unique device number assigned to it when the system is 
booted. Device numbers do not change unless the SOS.DRIVER file is 
changed and the system is rebooted. 

control_code: 1 byte value 

Range: $00..$FF 

This is the numberof the control request being made. All character device 
drivers respond to the following requests; 

$00 Reset device 

$0 1 Resto re d river's cont rol block 

$02 Set newline mode and 



Block devices do not respond to any control requests. 

Device drivers also may respond to other control requests. The complete 
list of control requests available for a device driver is included in the 
documentation accompanying that driver, 

conlrof jist; pointer 

This is a pointer to the buffer from which the device driver draws the 
control information. For the two requests above, the buffer is in one of 
these two formats: 



character 
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length 

value 



y control 
Sr list 
(values) 



Figure 10-4. Character Device Control Code $01 

The status list for each driver has a different format. See the manual 
describing that driver. 



isnewllne 

result 

newlinechar 

result 



Figure 10-5. Character Device Control Code $02 



The new line character is called the termination character in the Apple III 
Standard Device Drivers Manual. 



Each driver that defines its own additional control requests also defines 
buffer formats for those requests; see the documentation for that driver. 



Comments 

The length of the buffer pointed to by controMist must van/ depending 
upon the particular control request being made. 



Errors 






$11; 


BADNUM 


Invalid device number 


$21: 


CTLCODE 


Invalid control code 


$23: 


NOTOPEN 


Character device not open 


$25: 


NORESRC 


Resource not available 


$26: 


BADOP 


No control of block devices allowed 


$30..$3F 




Device-specific error 
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10.1.3 GET_DEV_NUM 



Device Call $84 



This call returns the device number 
of the driver whose device name is 
specified. The device need not be 
open. The dev_num returned is 
used in the D_ STATUS, 
D_CONTROL, and D_INFO calls. 

Required Parameters 



GET DEV NUM$84 



1 
3 



»2 



dew_naFne 

po'inter 



devnum 

result 



dev name: pointer 

This is a pointer to a string in memor/ containing the device name of the 
device whose numtier is to be returned: the first byte of the string is the 
number of bytes in the name; the rest are the bytes of the name itself. Note 
that this a device name, not a pathname. 



dev_num: 1 byte result 

Range: $01. .$18 

This is the device number of the device specified by dev_name. The name 
of a device can be changed by the System Configuration Program. 



Errors 



$10: DNFERR Device name not found 
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10.1.4 D_INFO 

This call returns the device name 
(and optior>ally, other information) 
about the device specified by dev_num 
The device's character file need not 
be open. D_INFO returns identifying 
information about the device's 
external status and interface to SOS; 
D_STATUS returns information 
about the internal status of the 
device and its driver. 

Required Parameters 

dev^num: 1 byte value 

Range: $01. .$18 

This is the device number of the 
device whose information is to be 
returned, obtained from the 
GET_DEV_NUM call. 

dev name: pointer 

This is a pointer to a sixteen-byte 
buffer into which SOS is to store 
the resulting device name: the first 
byte of the buffer is the number of 
bytes in the name; the rest are the 
bytes of the name itself. 

optionjisi: pointer 

This is a pointer to the optional 
parameter list if length is between 
$00 and $0A; otherwise it is ignored. 

length: 1 byte value 

Range: $00-.$0A 



Device Call $85 

D INPO $85 



$04 



devnum 

vafue 



dev name 

poinler 



Option list 

pointer 



length 

value 



slol_nimi 

result 



unit^num 

result 



devtype 

result 



result 



unused 



lotal_t}tocks 

result 



manutjd 

result 



versionnum 

result 



This is the length in bytes of the optional parameter list It specifies 
which optional parameters are supplied. 
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The values below tell the number of bytes in a list witfi complete 
parameters. If SOS receives an intermediate value, it does not take half 
a parameter, but reduces the length to the next defined value. 

$00 = no optional parameters 
$01 = slotnum 

$02 = slot num through unit num 
$03 = slot num through dev type 
$05 - slot num through sub type 
$07 = slot num through total blocks 
$09 = slot num through manuf id 
$0B = slot num through version num 

Optional Parameters 

slot_num: 1 byte result 

Range: $00..$04 

This is the slot number of the peripheral slot the device uses. Slot 
numbers $01 through $04 correspond to peripheral slots 1 through 4. Slot 
number $00 indicates the device does not use a peripheral slot. 

unll^num: 1 byte result 

Range; $00. .$FF 

This is the unit number of the device. Devices that are bundled together 
into one driver module are assigned unit numbers in ascending sequence, 
beginning w^ith $00. See the Apple III SOS Device Driver Writer's Guide 
for more details. 




This parameter has nothing to do with the logical unit numt^ers 
that Rascal associates with the devices. 



dev_type: 1 byte result 

Range: $00..$FF 



The dev_type byte, along with the following byte, is used for 
device classification and identification. This field specifies the 
generic family that the device belongs to. 
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The dev_type byte for SOS character devices has the following 
structure: 



6 5 

1 r 

W R 
I L. 



3 2 10 
1 \ 1 

X X X X 
I I I 



Bit 7 is cleared for all character devices. 

Bit 6 (W) is write allowed byte. It must be set for all character devices that 
accept data from the Apple III. 

Bit 5 (R) is the read allowed bit. It must be set for all character devices that 
send data to the Apple III. 

Bit 4 is reserved for future use and must always be cleared. 

The devjype byte for SOS block devices has the following structure: 



7 


6 


5 


4 


3 


2 


1 





1 


W 


1 -r 

Rem 

1 


Fmt 


1 

X 


1 1 

X 


X 

1 1 


X 



Bit 7 is set for all block devices. 

Bit 6 (W) is write allowed byte. It must beset for all block devices that 
accept data from the Apple III. 

Bit 5 (R) is the removable device bit. ft must be set for all block devices that 
use removable storage media, such as floppy-disk drives. 

Bit 4 is set if the driver can also format its device, 

subjype; 1 byte result 

Range; $00..$FF 

The device subtype identifies the specific device wfithin the generic family 
specified in devjype. 



unused: 1 byte 



70 SOS Reference Matiuat 



total blocks: 2 byte result 

Range: $0000,, $FFFF 

If the device is a block device, this parameter indicates the total numberof 
blocks it can access. If the device is a character device, this parameter 
returns $0000. The Apple Ill's built-in disk drive can access $01 18 blocks, 

manuf_id: 2 byte result 

Range: $0000..$FFFF 

The manufacturer identification code uniquely identifies the manufacturer 
of the driver. The currently assigned values are 

$0000 Unknown 

$0001 Apple Computer, Inc. 

version_num: 2 byte result 

Range: $0000.. $9999 

This is the version numberof the device driver The format is BCD (binary- 
coded decimal); no hexadecimal digits from $A to $F will appear in this 
result. 

Comments 

The foHowing values for devjype and subjype are assigned: 
dev_name devtype subtype 



RS232 printer (.PRINTER) 


$41 


mi 


Silentype printer ( SILENTYPE) 


$41 


Parallel printer (.PARALLEL) 


$41 




Sound port ( AUDIO) 


$43 




System console (.CONSOLE) 


$61 


$01 


Graphics screen (.GRAFIX) 


$62 




Onboard RS232 <.RS232) 


$63 


m 


Parallel card (.PARALLEL) 


$64 


$01 


Disk III (.01 through .04) 


$E1 




ProFiledisk (.PROFILE) 


$D1 


m 


Block device formatter: 






Disk III f.FiyiTDI ... .FIVITD4) 


$11 
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Please contact the PCS Division Product Support Department of Apple 
Connputer, Inc. if you wish to be assigned a dev_type, subjype, 
manur_id, or versior>_num. This will ensure that such codes are unique 
and are known to SOS and future application programs. 

Errors 

$11: BADNUM Invalid device number 

70.2 Device Call Errors 



The errors below are generated by SOS device calfs; some of them are 
also generated by SOS file calls. Other errors are listed in Appendix D. 

$10: Device not tound (DNFERR) 

The device name passed as a parameter to GET_DEV_NUM is not that 
of a device that is configured into the system: a device driver with that 
name was not in the S03.DRIVER file at the time the system was booted, 
or that device dnver was inactive. 

$11: Invalid device number (BADDNUM) 

The dev_num parameter does not contain the device number of a device 
configured into the system. 

$20: Invalid request code (BADREQCODE) 

This error is generated only for device requests, made by SOS to a device 
dhver. and should never be received as a result of a SOS call. 

$21: Invalid status or control code (BADCTL) 

The control (for D_CONTROL) or status (for D_STATUS) code is not 
supported by the device driver being called. 

$22: Invalid control parameter list (BADCTLPARM) 

The parameter list specified by the control parameter to the 
D_CONTROL call is not in the proper format for the control request 
being made. 
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$23: Device not open (NOTOPEN) 

The character device being referenced has not been opened by the file 
OPEN call. 

$25: Resources not available (NORESC) 

The device driver is unable to acquire the system resources (such as 
memory, I/O ports, or interrupts) it needs to operate. This error can also 
occur during a file OPEN call. 

$26: Call not supported on device (BADOP) 

The requested SOS call is not supported by the device. 

$27: I/O error (lOERR) 

The device driver is unable to exchange information vt/ith the device, due 
to a bad storage medium or communication line, or some other cause. If 
this happens on a flexible disk, remove and replacethedisk. and try again. 

$2B: Device write-protected (NOWRITE) 

The medium in this block device is write-protected. Remove the write- 
protect tab and try again. 

$2E: Disk switctied (DISKSW) 

The medium in the block device tias been removed and possibly replaced. 
This message is merely a warning, and occurs only the first time the call is 
made: the second time the call is made, it wiW be executed. 

Errors $30 through $3F are returned by individual device drivers, and 
relate to specific error conditions within those drivers. The error codes 
generated by a device driver are described in the manual describing that 
device driver. 



Memory Calls and Errors 73 

























































1 


i 


III 




















1 






—\ 




A 


Memory Calls and Errors 













74 11.1 Memory Calls 



75 


11 


1.1 REQUEST SEG 


77 


11 


1,2 FIND SEG 


81 


11 


1.3 CHANGE SEG 


83 


11 


1.4 GET SEG INFO 


85 


11 


1.5 SET SEG NUM 


87 


11 


1.6 RELEASE SEG 



88 11.2 Memory Call Errors 
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7t.t Memory Calls 



These calls are used by SOS to allocate memory tor interpreters, as 
explained in section 2.3. 

$40: REQUEST^SEG 

$41: FIND^SEG 

$42: CHANGE_SEG 

$43: GET_SEG_INFO 

$44; GET_SEG_NUM 

$45: RELEASE SEG 
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11,1.1 REQUEST_SEG Memory Call $40 

This call requests the contiguous 
region of mennory bounded by the 
base and limit segment addresses. 
A new segment is created if and 
only if no other segment currently 
occupies part orall of the requested 
region of memory. 



Required Parameters 

base; 2 byte value 

Range: $0020..$10FF 

This is the segment address (bank 
followed by page) of the beginning 
of the memory range requested. 

limit: 2 byte value 

Range: $0020..$10FF 

This is the segment address of the end of the memory range requested. 

segjd: 1 byte value 

Range: $00.,$7F 

This is the segment identification code of the requested segment. The 
caller can use this parameter to identify the type of information that the 
segment will contain. 

The highest four bits of the seg_id identify the owner of the segment: 
Segidrange Owner Contents 



$00to$0F SOS Kernel System code 

$10to$1F Interpreter Interpreter data 

$20 to $7F User User program and data 

The memory system does not check this parameter to ensure that 
It is in the proper range. 



REQUEST_S£G $40 
$04 

1 



bas« 

walue 



limit 
value 



seg id 

value 



g segnum 

result 
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seg_nuin: 1 byte result 

Range: $01. .$1F 

If the requested segment is available, this parameter returns the 
segment number of the segment granted. This number must be 
used to identify the segment in subsequent calls to 
CHANGE_SEG, RELEASE_SEG, or GET_SEG_1NF0. 

Comments 

Both the base and limit segment addresses must reside in switchable 
banks $00 through $0E, system bank $0F, or system bank $10. In 
addition, the base address must be less than or equal to the limit 
address. If the base and limit segment address parameters fail to 
meet the above criteria, then the segment m\i not be allocated and 
error BADBKPG will be returned. 

The ranges for base and limit are not continuous: these are the 
allowable segment addresses: 

$0020..$009F 
$01 20.. $01 9F 



$0E20..$0E9F 
$0F00..$0F1F 

$10A0,.$10FF 




SOS can keep track of $1 F segments 



Errors 



$E0: BADBKPG Invalid segment address (bank/page pair) 
$E1: SEGRQDN Segment request denied 
$E2: SEGTBLFULL Segment table full 
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11.1.2 FIND SEG 



Memory Call $41 



306 



search mode 

value 



3eg_id 

value 



pages 

value/result 



This call searches memory from find_seg $41 

high memory down, until it finds the 
first free space that is pages pages 
long and meets the search 
restrictions in search_mode. If 
such a space is found, it assigns 
this free space to the caller as a 
segment (as in REQUEST_SEG), 
returning both the segment number 
and the location in memory of the 
segment. If a segment with the 
specified size is not found, then the 
size of the largest free segment 
which meets the given criterion will 
be returned in phages. !n this case, 
however, error SEGRQDN will be 
returned, indicating that the 
segment was not created. 

Required Parameters 

search_mode: 1 byte value 

Range: $00.. $02 

This parameter selects one of three constraints to place upon the 
segment search: 



base 

result 



IFmit 

result 



segnum 

result 



$00: may not cross a 32K bank boundary 
$01 : may cross one 32K bank boundary 
$02: may cross any 32K bank boundary 
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seg_id:1 byte value 

Range: $00..$7F 

This is the segment identification code of the requested segment. The 
caller can use this parameter to identify the type of information that the 
segment wtll contain. 

The highest four bits of theseg_id identify the owner of the segment 
Segjd range Owner Contents 



$00 to $0F SOS Kernel System code 

$10to$1F Interpreter Interpreter data 

$20 to $7F User User program and data 

The memory system does not check this parameter to ensure that it is in 
the proper range. 

pages: 2 byte value/result 

Range: $0001. .$FFFF 

li^is is the the number of contiguous pages to search for. If no free space 
is found that contains tliis many pages, then the memory system will 
return in this parameter the size of the largest free space it can find; the 
SEGRQDN error is also generated. A page count of $00 always returns 
error BADPGCNT 

base: 2 byte result 

Range: $0020..$0E9F 

This is the the segment address of the beginning of the new segment, 

limit: 2 byte result 

Range: $0020..$0E9F 

This is the segment address of the end of the new segment. 

seg_num: 1 byte result 

Range: $01..$1F 

This is the the segment number of the segment granted. This number 
must be used to identify the segment in subsequent calls to 
CHANGE SEG, RELEASE SEG, orGET SEG INFO, 
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Comments 

FIND_SEG does not search the system banks $0F and $10. 

The base and limit parameters both return $0000 if the segment is not 
granted; even though pages returns the length of the largest available 
segment, base and limit do not return its location. 



Errors 



$E1: 
$E2: 
$E5: 
$E7: 



SEGRQDN Segment request denied 

SEGTBLFULL Segment table fulf 

BADSRCHMODE Invalid search mode parameter 

BADPGCNT Invalid pages parameter ($00) 
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11.1.3 CHANGE_SEG 

This call changes either the base 
or limit segment address of the 
specified segment by adding or 
releasing the number of pages 
specified by the pages parameter. 
If the requested boundary change 
overlaps an adjacent segment or 
the end of the memory, then the 
change request is denied, error 
SEGRQDN is returned, and the 
maximum allowable page count is 
returned in the pages parameter. 

Required Parameters 

seg_num: 1 byte value 

Range: $01..$1F 

This is the segment number of the segment to be changed. 

change mode: 1 byte value 

Range: $00, .$03 

The change mode indicates which end (base or limit) of the segment to 
change, and whether to add or release space at that end. 

$00: Release from the base (decrease size) 

$01 : Add before the base (increase size) 

$02: Add after the limit (increase size) 

$03: Release from the limit (decrease size) 

pages: 2 byte value/result 

Range: $0001.,$FFFF 

This is the number of pages to add to or release from the segment. If too 
many pages are added to or removed from the segment, then the segment 
is not changed, and the maximum number of pages that can be added or 
removed in the requested change_mode is returned in this parameter, 
along with a SEGRQDN error. 



Memory Call $42 

CHANGE SEG$42 



$03 



^ seg_nurn 

value 



2 change made 



pages 

value/result 
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Comments 

You cannot move both ends of a segment at once. 

If the segment was granted by FIND_SEG, a CHANGE_SEG 
operation will not heed the ban It-crossing criterion that was used in 
finding the segment. If you request a segment that does not cross a 

bank boundary, then increase it with CHANGE SEG, the larger 

segment may cross a bank boundary. 

Errors 

$E1 SEGRODN Segment request denied 
$E3 BADSEGNUM Invalid segment number 
$E6 BADCHGMODE Invalid change mode parameter 



Memory Calls and Errors 



63 



11.1.4 GET SEG_INFO 



Memory Call $43 



GET SEG INFO $43 



$05 



seg_num 



base 

result 



limit 

resull 



This call returns the beginning and 
ending locations, size in pages, and 
identification code of the segment 
specified by seg_num. 

Required Parameters 

seg_num: 1 byte value 

Range: $01..$1F 

This returns the segment number of 
an existing segment, 

base: 2 byte result 

Range: $0020..$109F 

This returns the segment address of 
the beginning of that segment. 

limil: 2 byte result 

Range: $0020.,$109F 

This returns the segment address of the end of that segment. 

pages: 2 byte result 

Range: $0001.,$FFFF 



pages 

result 



result 



This returns the number of pages contained by the segment. 



segjd: 1 byte result 

Range: $00..$7F 

This returns the identification code of the segment. The highest four bits 
of the seg_id identify the owner of the segment; 



Segjdrange Owner Contents 



$00 to $0F SOS Kernel System code 

$1 to $1 F I nterpreter I nterpreter data 

$20 to $7F User User program and data 
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Errors 

$E3: BADSEGNUM Invalid segment number 
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11.1.5 GET_SEG_NUM 

This call returns the segment 
number of the segment, if any, that 
contains the specified segment 
address. 

Required Parameters 

seg_address; 2 byte value 

Range: $0020,.$ 109F 

This is the segment address in 

question- 



Memory Call $44 



GET SEG NUM$44 



- — 






$02 




seg_ address 




value 




segnum 




result 



seg_num: 1 byte result 

Range: $0r.$1F 

This is the segment number of the segment that contains the specified 
segment address. 

Comments 

You may make a subsequent call to GET_SEG_INFO with the resultant 
segment number to determine the ownership of that segment. 

Errors 



$E0: 
$E4; 



BADBKPG Invalid segment address (bank/ page pair) 
SEGNOTFND Segment not found 
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11.1.6 RELEASE_SEG 



Memory Call $45 



This call releases the memory 
occupied by the segment specified 
by seg_num, by removing the 
segment from the segment table. 
The space formerly occupied by 







RELEASE SEGS45 



3eg_num 

value 



S01 



the released segment is returned to ' ' 

free memory. If seg_num equals 

zero, then all nonsystem segments (those with segment identffication 
codes greater tfian $0F) will be released. 

Required Parameters 

seg_num: 1 byte value 

Range: $00..$1 F 

This is the segment number of the segment to be released. If seg_num is 
$00, then alt segments not owned by SOS are released. 



Errors 



$E3 



BADSEGNUM Invalid segment number 
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1 1.2 Memory Call Errors 



The errors below are generated by SOS rnenDory calls, For other errors, 
see Appendix D. 

$E0: Invalid segment address (BADBKPG) 

The segment address has an invalid bank number, page number, or both. 

$E1: Segment request denied (SEGRQDN) 

No segment can be created that meets the caller's size and boundary 



$E2: Segment table lull (SEGTBLFULL) 

SOS can keep track of no more segments: existing segments must be 
released or consolidated if more segments are needed. 



$E3; Invalid segment number (BAOSEGNUM) 

The seg_num passed is not that of a currently existing segment. 

$E4: Segment not found (SEGNOTFND) 

For GET_SEG_NUM, no segment in the system contains the segment 
address specified. 

$E5: Invalid search mode parameter (BADSRCHftflODE) 

For FIND^SEG, the search_mode parameter is invalid (greater than $02). 

$E6: Invalid change mode parameter (BAD CHG MODE) 

For CHANGE_SEG, the change^mode parameter is invalid (greater 
than $03). 

$E7; Invalid pages parameter (BADPGCNT) 
The pages parameter is invalid (equal to $00). 



criteria. 




SOS can keep track of $1F segments. 
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90 12.1 Utitity Calls 

91 12,1.1 SET_FENCE 
93 12.1.2 GET_FENCE 
95 12.1.3 SET_TIME 
97 12.1.4 GET__TIME 

99 12.1.5 GET_ ANALOG 

103 12.1.6 TERMINATE 

104 12.2 Utility Call Errors 
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t2.1 Utility Calls 



The following system calls deal with tfie system clock/calendar, the 
event fence, the analog input ports, and other general system 
resources. 

$60: SET^FENCE 

$61: GET__FENCE 

$62: SET_TIME 

$63: GET_T1ME 

$64; GET_ ANALOG 

$65; TERMINATE 




12.1.1 SET_FENCE 



Utility Call $60 



This call changes the current value 
of the user event fence to the value 
specified in the fence parameter. 







SET FENCE $60 



$01 



Required Parameters 



fence 



fence: 1 by te value 

Range: $00..$FF 

This parameter contains the new value of the user event fence for the 
operating system's event mechanism. Events with priority less than or 
equal to the fence will not be serviced until the fence is lowered. 

Errors 

No errors are possible. 
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12.1.2 GET FENCE 



Utility Call $61 



This call returns the current value of 
the user event fence. 



GET FENCE S61 







$01 



Required Parameters 



(ence 

result 



fence; 1 byte result I — 

Range: $00-.$FF 

This parameter returns the current setting of the user event fence. Events 
with priority less than or equal to the fence will not be serviced until the 
fence is lowered. 

Errors 

No errors are possible. 
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12.1.3 SET TIME 



Utility Call $62 



This call sets the system clock to 
the contents of a buffer located at 
the specified address. If the system 
has no functioning clock, 



SET TIME $62 



$01 



SET_TIME stores the contents of 
the buffer as the last valid time, to 
be returned on the next 



2 



time 

pointer 



GET_TIME can. ' 1 

Required Parameters 
time: pointer 

This is a pointer to an 1 8-byte buffer containing the current date and time 
The information is specified as an 1 8-byte ASCII string whose format is 

YYYYMMDDXHHNNSSXXX 

The meaning of each field is as below: 



Field 


Meaning 


Minimum 


Maximum 


YYYY: 


Year 


1900 


1999 


MM: 


Month 


00 or 01 


12 (December) 


DD: 


Date 


00or01 


28, 30, or 31 


X: 


Ignored 






HH: 


Hour 


00(Midnight) 


23 (11 :00 p.m.) 


NN: 


Minute 


00 


m 


SS: 


Second 


00 




XXX: 


Ignored 






For example, 


December 29, 


1980, at 9:30 a.m. 


would be specified by the 



string ■'198012290093000000", 
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Comments 

On input, SOS replaces the first two digits of tine year with "19" and 
ignores the day of the week and the millisecond. SOS calculates the day 
from the year, month, and date. 

SOS does not check the the validity of the input data to make sure each 
field is in the proper range. The clock makes several restrictions: it rejects 
any invalid combination of month and date. The clock only accepts dates 
in the range 1 ..30 if the month is 4, 6, 9, or 1 1 ; it only accepts dates in the 
range 1 ..28 if the month is 2: February 29 is always rejected. 

SET_TIME attempts to set the hardware clock, whether or not it is 
present and functioning. It also stores the new time in system RAM as the 
last known valid time; this time will be returned by all subsequent 
GET_TIME calls if the hardware clock is missing or malfunctioning. 

The clock does not roll over the year 

The format of the SET_TIIVIE string is the same as that of the GET_TIME 

result, except that SET TIIVIE ignores the day of the week and the 

millisecond fields. 

Errors 

No errors are possible. 
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12.1.4 GET_TIME Utility Call $63 

This call reads the time from the 
system ctock and returns it to the 
buffer located at the specified 
address. If the system has no 
functioning clock, GET_TIME 
returns the last known valid time. 



Required Parameters 
time: pointer 

This is a pointer to an 1 8-byte buffer containing the current date and time. 
The information is specified as an 1 8-byte ASCII string whose format is 

YYYYMMDDWHHNNSSUUU 
The meaning of each field is as below: 



Field 


Meaning 


Minimum 


Maximum 


YYYY: 


Year 


1900 


1999 


MM: 


Month 


00 or 01 


12 (December) 


DD: 


Date 


00 or 01 


28, 30, or 31 


W: 


Day 


01 (Sunday) 


07 (Saturday) 


HH: 


Hour 


00 (Midnight) 


23 (11 :00 p.m.) 


NN: 


Minute 


00 




SS: 


Second 


00 


59 


UUU: 


Millisecond 


000 


999 



For example. Friday, March 21, 1980. at 1:27:41 .001 p.m., would be returned 
as "198003216132741001". 

Comments 

If the hardware clock is not operational, the utility manager retrieves 
the last known valid time from system RAM. If no last known valid time 
is stored, GET_T1ME returns a string of eighteen ASCII zeros: 
"000000000000000000" 



GET_TIM£$63 






$01 


1 


lime 




pointer 


2 
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SOS calculates the day of the week from the year, month, and date. 

The clock will only generate dates in the range 1 ..30 if the month is 4, 6, 9, 
or 1 1; it will only generate dates in the range 1 ..28 if month is 2: February 29 
will never be generated by a system with a functioning clock. A system 
without a functioning clock can return February 29 if that month and date 
have been set by a SET_TIME call. 

The clock does not roll over the year. 

You must ensure that the buffer pointed to by time can hold all eighteen 
($12) bytes, to avoid overwriting other data. 

Errors 

No errors are possible. 
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12.1.5 GET_ANALOG 

This call reads the analog and 
digital inputs from an Apple III 
Joysticic connected to port A or B 
on the back of the Apple Mi. 

Required Parameters 



joy_mode: 1 byte value 

Range; $00.. $07 

This parameter specifies the 
joystick! inputs to be read. For each 
value of joy_mode. the following 
inputs will be read: 

Joy_mode Port Buttons/Switches Horizontal Vertical 



$00 


B 


JS0-B, JS0-SW 






$01 


B 


JS0-B, JSfl-Sw 


JS0-X 




$02 


B 


JS0-B, JS0-SW 




JS0-Y 


$03 


B 


JS0-B, JS0-SW 


JS0-X 


JS0-Y 


$04 


A 


JS1-B, JS1-SW 






$05 


A 


JSVB, JS1-SW 


JSI-X 




$06 


A 


JS1-B, JS1-SW 




JS1-Y 


$07 


A 


JS1-B, JSI-Sw 


JS1-X 


JS1-Y 



The names for these variables are those used in the Apple III Owner's 
Guide, Appendix C. These eight variables are returned by the 
joy_status parameter. 



Utility Call $64 

GET^ANALOG $64 
1 



joy mode 



JSn-B 

result 

B JSn-Sur 

f= result 

1 result 

JSn-Y 

result 
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joy_slatus: 4 byte result 

Range: $00000000.. $FFFFFFFF 

This 4-byte field is treated as one parameter by SOS, Here we 
subdivide it into tour 1-byte fields for clarity; n represents the 
numbers of the joystick (1 or 2) as determined by the joy_mode 
parameter 

JSn-B; 1 byte result 

Range: $00..$FF 

This digital output returns $00 if the button is off and returns 
$FF if the button is on. 

JSn-Sw: 1 byte result 

Range: $00..$FF 

This digital output returns $00 if the switch is off and returns $FF 
if the switch is on. 

JSn-X: 1 byte result 

Range: $00..$FF 

This analog output returns a value from $00 to $FF 
corresponding to the horizontal position of the joystick. A 
position that was not read (due to the joy_mode parameter) 
returns a byte of $00. 

JSn-Y: 1 byte result 

Range; $00..$FF 

This analog output returns a value from $00 toSFF 
corresponding to the vertical position of the joystick. A position 
that was not read (due to the joy_mode parameter) returns a 
byte of $00. 



Utility Calls and Errors 



10t 



Comments 

An input device other than a joystick can be read, provided (a) it uses the 
same pins for analog and digital inputs, and (b) each pin produces the 
correct signals, as described in \he Apple III Owner's Guide. 

Both buttons of the selected joystick are always read and returned. 

Reading tlie analog inputs slows down the execution speed of this call 
and should be avoided when unnecessary. 

JSn-B. JSn-Sw, JSn-X, and JSn-Y all return results of $FF if no joystick is 
attached to the port- 

The XNORESRC error will be generated if an attempt is made to read Port 
A and a device driver (such as the Silentype driver) has already claimed 
the use of that port 

The parm_count is $02, not $05. 
Errors 

$25 XNORESRC Resource not available 
$70 BADJMODE Invalid joystick mode 
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12.1.6 TERMINATE 

This call clears memory, clears the 
screen, and displays INSERT 
SYSTEM DISKETTE & REBOOT in 
40-columri black-and-white text 
mode on the screen. The system 
then hangs, and waits for the user 
to press CONTROL-RESET 
and reboot. 

Required Parameters 
None 



Utility Call $65 



TERMINATE $65 



p ' 


BRK = S00 






jD 1 


caJI num = $65 

" valve 










p + 2 


pami_list = p 

pointer 




p + 3 




r 



Comments 

Only the SOS Call Block is shown for this call. Since this call has no 
parameters, the paranieter_count is $00. Thus the parameter list pointer 
must point to a byte containing $00. The most convenient such byte is the 
BRK opcode beginning the TERMINATE call, so this call customarily bites 
its own tail. 

Before issuing a TERMINATE call, the interpreter should close all open 
files. This Will ensure that all I/O buffers are written out, and all file entnes 
updated, while the necessary information still exists. 

This call is the recommended way to leave a program. It provides a clean 
exit to a program, and leaves no traces of it in memory for the user's 
examination. It can be used in conjunction with a copy-protection scheme 
to protect a program from piracy. It also provides a hook that could be 
used to return control to a future command interpreter. 

Errors 

No errors are possible. This is an excellent call for beginners. 
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72.2 Utility Call Errors 

One error can be generated by one of the utility calls; other errors are 
listed in Appendix D. 

$70: Invalid Joystick Mode (8 AD J MODE) 
The joy_mode parameter is greater than $07. 
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Version: SOS 1.1, 1.2 and 1.3 
Classification: 

Single-task, configiirable, interrupt-driven operating system- 
File system— hierarchical, tree file structure. 
Device-Independent 1/0. 

CPU Architecture: 

Address enhanced 6502 instruction set. 

Supports both bank-switched and enhanced indirect addressing. 

Separate execution environments for user and SOS including 
private zero and stack pages. 

System Calls: 

Based on 6502 BRK instruction, pointer, and value parameter 
types. 

Error codes returned via A register. 

All other CPU registers preserved upon return. 

Optional parameter lists for future expansion. 

File Management System: 

Hierarchical file structure. 
Pathname prefix facility. 

Byte-oriented file access to both directory /user files and device 
files; 

Dynamic, non-contiguous file allocation on block devices. 
Automatic buffering (current index block and data block). 
Dynamic memory allocation of file buffers. 
Block size (512 bytes). 

File protection: rename/destroy/read/write access attributes. 
File level assignment on Open. 
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Automatic date/time stamping of files. 

Automatic volume logging/swapping, supported by system 
message center. 

Multiple volumes per block device can be "open" simultaneously. 
Sparse file capability: 

maximum number of active volumes = 8 

maximum disk size = 32 Mbytes 

maximum user file size = 16 Mbytes 

maximum file entries in volume directory = 51 

maximum file entries in a subdirectory - 1663 

file names — maximum 15 characters 

pathnames — maximum 128 characters 
File system calls: 



CREATE 


READ 


DESTROY 


WRITE 


RENAME 


CLOSE 


SET_FILE_INFO 


FLUSH 


GET_FILE_INFO 


SET_MARK 


VOLUME 


GET_MARK 


SET_PREFIX 


SET_EOF 


GET_PREFIX 


GET_EOF 


OPEN 


SET_LEVEL 


NEWLINE 


GET_LEVEL 



Device Management System: 

Block and cfiaracter device classes. 

Standardized interface for block and for character devices. 

All devices are named and configurable. 
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Support for synchronous, interrupt, and DMA-based I/O. 
maximum number of devices = 24 
maximum number of block devices = 1 2 

Device system calls: 

GET_DEV_NUM D_STATUS 
D_INFO DECONTROL 

Memory/Buffer Management System: 

All memory allocated as segments. 

Supports maximum of 51 2 Kbytes RAM. 

System buffers allocated and released dynamically. 

System buffer ctiecksum routine for data integrity. 

Memory system calls: 

REQUEST_SEG GET_SEG_INFO 
FIND_SEG GET_SEG_NUM 
CHANGE_SEG REL_SEG 

Additional System Functions: 

System clock/calendar 
(year/month/day/weekday/hour/minute/second/ms). 

Joysticks: reads X and Y axes, pushbutton, and switch. 

TERMINATE call provides ciean program termination and clears 
memory. 

System calls: 

SET_TiME TERMINATE 

GET TIME GET ANALOG 
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Interrupt Management System: 

Receives hardware interrupts (IRQ, NM I) and system calls (BR K), 
Hardware resource allocation and deallocation- 
Dispatches to driver interrupt handlers. 

Event Management System: 

Priority-based event signaling. 

Event handlers preempted by higher priority events. 

Events with equal priorities process FIFO, 

Event fence delays events with priority less than fence. 

Event system calls: 

SET_FENCE GET_FENCE 

System Configuration; 

Menu-driven system-configuration editor (System Configuration 
Program). 

Can add, remove, and modify drivers and can select the 
keyboard-layout and system-character-set tables. 

Standard Device Drivers: 

Floppy disk (.D1 , .D2, .03. .04) 

143,360 bytes (formatted) per volume. 

Automatically reports mounting of a new volume, 

Built into SOS kernel. 
Console (.CONSOLE) 

Interrupt-driven keyboard (supports type-ahead). 

Configurable keyboard-layout table (via SCP). 

Raw-keystroke and no-wait input modes. 

Event handler supports anykey and attention character 

Optional screen echoing. 
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Console control modes: 

video on/off 
flush type-ahead buffer 
suspend screen output 
display control characters 
flush screen output 

Cursor positioning commands. 

Viewport set, clear, save, and restore commands. 

Horizontal and vertical scrolling. 

Text modes: 24 x 80 and 24 « 40 B&W and 24 x 40 color 
(normal and inverse). 

Configurable system character set table (via SCP). 

Character set can be changed under program control at 
any time. 

Screen read command. 

Graphics (.GRAFIX) 

Displays graphical and textual information 
simultaneously. 

Graphics modes: 

560 X 192 and 280 x 192 in B&W video, 
280 X 192 and 140 x 192 in 16 colors. 

Point-plotting and line-drawing commands using graphics 
viewport and pen. 

Raster block picture operations. 

Color operator table, controls color overwrite 

Transfer modes allow binary operations on the drawing 
color and the current screen color. 

Allows use of either the system character set or an 
alternate character set to display ASCI) text on the 
screen. 

Single or dual graphics screens. 
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General purpose communications {.RS232) 
RS-232-C Interface. 

Configurable data rates from 1 10 to 9600 baud. 

Configurable protocols, including XON/XOFR ETX/ACK, 
and ENQ/ACK. 

Interrupt-driven, buffered, bi-directional data transfer, 
Hardware handshaiting option. 
Serial printer (.PRINTER) 

RS-232-C interface. 

Configurable data rates from 110 to 9600 baud. 
Interrupt-driven and buffered (output only). 
Hardware fiandshaking option. 
Audio (.AUDiO) 

64 volume leveis. 

Produces tones from 31 to 5090 Hz (over 7 octaves). 
Duration range from to 5 sec (increments of 1/60 sec). 
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B.1.1 Choosing Calls and Other Functions 


116 




8.1. 2 Input Parameters 


117 


B.2 


The Data Buffer 


117 




8.2. 1 Editing the Data Buffer 
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B,3 


The String Buffer 
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B.4 


Leaving ExerSOS 
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ExerSOS is a interactive BASIC program that lets you make SOS calls 
from ttie keyboard without writing a special assembly-language 
program to test eacti call. It is intended to let you try out calls to see 
how they work. ExerSOS lets you choose a call from a menu, then 
prompts you for each of the call's input parameters, and gives you 
the correct output parameters or error message, 

B.I Using ExerSOS 



To use ExerSOS, insert the ExerSOS disk into the built-in drive and 
press CONTROL-RESET. After the introductor/ displays you will 
see the Main Menu. 

B.1.1 Choosing Calls and Other Functions 

The Main Menu presents you with a choice of functions, Typing 
will EXIT ExerSOS, The first 35 of these functions are SOS calls 
{listed below by type), The remainder are special functions 
available within ExerSOS. The full list of functions is 

File Calls: 



$C0 


CREATE 


SCI 


DESTROY 


$C2 


RENAME 


$C3 


SET FILE INFO 


$C4 


GET FILE INFO 


$C5 


VOLUME 


$C6 


SET PREFIX 


$C7 


GET PREFIX 


$C8 


OPEN 


$C9 


NEWLINE 


$CA 


: READ 


$CB 


: WRITE 


$CC 


: CLOSE 


$CD 


: FLUSH 
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$CE: SET_MARK 

$CF: GET_MARK 

$D0: SET_EOF 

$D1: GET_EOF 

$D2: SET_LEVEL 

$D3: GET LEVEL 



Device Calls: 

$82: D_STATUS 

$83: D_ CONTROL 

$84: GET_DEV_NUM 

$85: D INFO 



Memory Calls: 



$40: 


REQUEST SEG 


$41: 


FfND SEG 


$42: 


CHANGE SEG 


$43: 


GET SEG INFO 


$44: 


GET SEG NUM 


$45: 


RELEASE_SEG 


Utility Calls: 




$60: 


SET FENCE 


$61: 


GET FENCE 


$62: 


SET TIME 


$63: 


GET TIME 


$64: 


GET ANALOG 



ExerSOS Utilities: 

$1: Display Directory 

$2: Display Open Files 

$3: Display Active Memory Segments 

$4; Display/Edit Contents of Data Buffer 
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B.1.2 Input Parameters 

When you select a SOS call from the Main Menu, the display is replaced 
by a split-screen menu showing the name of the call at the top. The left 
hair of the screen is used tor typing input parameters to the call; the right 
is used to show the resultant SOS call error and any output parameters. 
You will then be prompted for each input parameter, following the 
description of the call in the SOS Manual. If you wish to return to the Main 
Menu, type a backslash (\ ) and press RETURN. 

All parameters have the same names as in this manual, and appear in 
the same order as in the description of the SOS call in Volume 2. Pointer 
parameters, however, are omitted, as all values and results are passed 
interactively, rather than by building a table in memory and passing its 
address. 

In some cases, a range of legal values is displayed; if your entry falls 
outside that range, you will be prompted again. For example, the first 
prompt you encounter in the READ call is 

I ref^num [0,.,255] - 

If you respond to this with an out-of-range value, the prompt will be 
repeated. 

You may also type data in hexadecimal by preceeding a value with a 
dollar sign ($). Some input fields have a fixed dollar sign: these fields 
require hex input. SOS calls requiring no input display 

I [None] 

before reporting the results of the call, 

When typing an input parameter, you can use the ESCAPE key to edit 
the input, as in BASIC, 

Several SOS calls employ an optional parameter list along with a length 
parameter. For those calls, ExerSOS asks you for the length and 
selectively prompts or displays information as requested. 
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a.2 The Data Buffer 



ExerSOS maintains two buffers you should be aware of: the data buffer 
and the string buffer. ExerSOS alone locates the 16K data buffer in 
memory. All I/O operations (READ, WRITE) use the data buffer. Hence, 
a READ call followed by a WRITE call will transfer bytes from one file 
to another 

In order to ensure the return of This 16K space to the system, 
always exit ExerSOS through the Main Menu, never by typing 
CONTROL-C. If you should accidentally exit ExerSOS, reboot 
by pressing CONTROL-RESET, 

B.2. 1 Editing the Data Buffer 

The Display/Edit function allows you to select any of the 64 256-byte 
pages of memory occupied by the data buffer, and displays that page in 
hex with the ASCII equivalents on the right side of the screen. You are 
then placed in Edit mode with the cursor (denoted by matching "[..]") 
positioned in the upper-right corner. You can move the cursor through 
the use of the four arrow keys. 

You can alter the contents of a byte by typing a hex digit, (that is, 0..9, 
A..F, a..f). Note that as you do so, the value you type is placed in the 
low-order nibble of the target byte, and the value that was in the low-order 
nibble moves to the high-order nibble. You may terminate the input to a 
byte by pressing RETURN, which accepts the new value, or ESCAPE, 
which restores the original value. 

If you press ESCAPE while you are in the cursor-positioning phase, you 
exit from Edit mode and have the choice of returning to the Main Menu 
or displaying another page of the buffer 
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B.3 The Siring Buffer 



The string buffer is used by many of the calls as temporary storage any 
time a pathname or device name is passed into or out of a SOS call. 
Additionally, the D_STATUS and D_CONTROL calls use the string 
buffer for the STATUS_LIST and CONTROL_LIST, respectively. 

The following SOS calls require some further user input: 

D_STATUS 

In addition to the SOS-required input parameters, ExerSOS 
prompts you for two more items. The first prompt, 

I Initialize Buffer [Y/N]- 

lets you initialize the string buffer by typing Y, or leave its current 
contents intact by typing N. Usually, you will initialize it, to make 
sure no garbage from a previous call obscures your results. 
However, in some cases, you may wish to make a status call, then 
change something with a control call, then check the buffer with 
a status call again: in such a case do not initialize the buffer. 

The second prompt, 

1^ Amount of output— 

asks you how many bytes of the string buffer you wish to see. If 
you specify more bytes than are in the status list, the remaining 
bytes will be either zeros or garbage, depending on your response 
to the "Initialize?" prompt. 

D_CONTROL 

After you specify thedev_r)Ufn and controi_code. ExerSOS allows 
you to specify the control list from either of two places. If you 
type a "0" to the "Length of input" prompt, the call is made from 
the current value of the string buffer, if you respond to the prompt 
with a value larger than 0, you are prompted for each byte of 
the control list. The resultant string is moved into the string buffer. 
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B.4 Leamng ExerSOS 



To leave ExerSOS, return to the Main Menu and type 0. You will be asked 
to confirm your intention: type Y to exit (any other reply will return you to 
the Main Menu). ExerSOS will drop into BASIC, and you will be able to run 
another BASIC program, or reboot by pressing CONTROL- RESET. If you 
leave ExerSOS inadvertently, as by typing CONTROL-C, you should 
reboot. If you try to RUN the program without rebooting, you will have 
lost the 16K space atlocated to the data buffer. 



1 20 SOS Reference Manual 



Makelnterp 121 




122 SOS Reference Manual 



Makelnterp is a program that takes an assembly-language code file 
produced by the Apple III Pascal Assembler and converts it to the proper 
format for a bootable SOS.INTERP file. If you are writing an interpreter, 
this makes it unnecessary for you to know the details of interpreter file 
format, and protects you from future changes in this format. 

To use Makelnterp, boot Pascal and insert the ExerSOS disk into, say, 
.D2- Now execute {that is, type X) 

.D2/MAKEINTERP.C0DE 

Then type the input pathname, the name of the interpreter code file, for 
example, 

.D2/ INTER P. CODE 
and the output pathname, say, 

.D2/S0S.INTERP 
As the disk spins, you see this message displayed: 



Converting Files 




When the conversion is complete, Makelnterp displays the message 




and returns you to the Pascal command line. 



All pathnames must be complete, with suffix. If you type any invalid input, 
you will have to execute the program again. 
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SOS detects two types of errors: 

• Non-fatal SOS errors, occurring during a SOS call, that are 
detected and flagged; 

• Fatal SOS errors, occurring during a SOS call or interrupt 
sequence, that signal such a substantial irregularity that the 
system cannot continue to operate, 

In addition, the SOS bootstrap loader detects bootstrap errors, which 
occur only when the system is starting up. 

The reporting mechanism for non-fatal SOS errors is discussed in 
Volume 1, section 8.4. The error code is returned in the accumulator after 
a SOS call: an error code of $00 means no error was encountered in 
the call. The error code is normally used by the interpreter to display a 
message to the user, to repeat an operation, or to take some other action. 

Bootstrap errors and fatal errors occur when an error condition is so 
critical that no recovery is possible. These errors cause their own 
messages to be displayed on the screen, as no interpreter is in place 
to interpret them. These errors are discussed in detail in section D.3. 



D. 1 Non-Fatal SOS Errors 



Explanations of the general system errors are given in section 8,4 of 
Volume 1 , Explanations of the other non- fatal system errors are given 
in Volume 2. The list below, numerically ordered, is for easy reference. 
Three things are listed for each error: the error number, a suggested 
name for the assembly-language routine handling the error, and a 
suggested error message for the interpreter to display on the screen. 



D. 1 1 General SOS Errors 

(See secUon 8,4J 



$01:BADSCNUM 
$02: BADCZPAGE 
$03: BADXBYTE 
$04; BADSCPGNT 
$05: BADSCBNDS 



Invalid SOS call number 
Invalid caller zero page 
Invalid indirect pointer X-byte 
Invalid SOS call parameter count 
SOS call pointer out of bounds 
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D.1.2 Device Call Errors 

(See section 1B.2) 



$10:DNFERR 
$11: BADDNUM 
$20: BADREQCODE 
$21:BADCTLC0DE 
$22; BADCTLPARM 
$23; NOTOPEN 
$25; NORESRC 
$26: BADOP 
$27: lOERROR 
$2B: NOWRITE 
$2E: DISKSW 
$33..$3F: 



Device not found 
Invalid device number 
Invalid request code 
Invalid status or control code 
Invalid control parameter list 
Device not open 
Resources not available 
Invalid operation 
I/O error 

Device write-protected 
Disk switched 
Device-specific errors 



0,7.3 File Call Errors 

(See section 9.2) 



$40: BADPATH 
$41;CFCBFULL 
$42: FCBFULL 
$43: BADREFNUM 
$44: PATHNOTFND 
$45: VNFERR 
$46: FNFERR 
$47: DUPERR 
$48: OVRERR 
$49:DIRFULL 
$4A: CPTERR 
$4B:TYPERR 
$4C: EOFERR 
$4D: POSNERR 
$4E: ACCSERR 
$4F: BTSERR 



$50 
$51 
$52 
$53 



FILBUSY 
DIRERR 
NIOTSOS 
BADLSTCNT 



$55: BUFTBLFU LL 



Invalid pathname syntax 

Character File Control Block full 

Block File or Volume Control Block full 

Invalid file reference number 

Path not found 

Volume not found 

File not found 

Duplicate file name 

Overrun on volume 

Directory full 

Incompatible file format 

Unsupported storage type 

End of file would be exceeded 

Position out of range 

Access not allowed 

Buffer too small 

File busy 

Directory error 

Not a SOS volume 

Length parameter invalid 

Buffer table full 
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$56; BADSYSBUF 
$57: DUPVOL 
$58: NOTBLKDEV 
$59: LVLEHR 
$5A: BtTMAPADDR 



Invalid system buffer parameter 
Duplicate volume 
Not a block device 
invatid level 

Invalid bit map address 



D.1.4 Utility Call Errors 

(See section 12.2) 

$70: BADJOYMODE Invalid ioy_mode parameter 



D.1.5 Memory Call Errors 

(See seclion 10.2) 



$E0: BADBKPG 
$E1:SEGRQDN 
$E2: SEGTBLFULL 
$E3: BADSEGNUIvl 
$E4: SEGNOTFND 
$E5: BADSRCHMODE 
$E6: BADCHGMODE 
$E7: BADPGCOUNT 



Invalid segment address 
Segment request denied 
Segment table full 
Invalid segment number 
Segment not found 
Invalid search_mode parameter 
Invalid change^mode parameter 
Invalid pages parameter 



D.2 Fatal SOS Errors 



If SOS encounters an internal error from wfiich it cannot recover, it 
displays an error message (including the code number of the error that 
occurred) on the screen, beeps the speaker, and hangs. The only 
recovery possible ts to reboot. 

The fatal error codes and conditions are listed below. The phrase 
following the number is a convenient name for the error, but no 
interpreter will be able to display it to the user, as SOS will not be 
around to help. 



Error Messages 121^ 



Invalid BRK (BADBRK) 

A BRK software interrupt was encountered within SOS. As SOS is not 
reentrant, it is not allowed to make SOS calls to itself; making such a cali 
is an unrecoverable error and means that the memory region containing 
SOS has been scrambled. 

$02: Invalid Interrupt (BADINT) 

An interrupt occurred that cannot be acknowledged by SOS. The 6502's 
IRQ or NMI line was pulled down, but either polling did not reveal the 
device that performed the interrupt, or no device driver had claimed that 
interrupt. 

$04: Invalid NMI (NMI HANG) 

A request was made for SOS to lock the RESET/NMI key, but a device 
is currently attempting to perform a NMI interrupt. If the interrupt is not 
granted and handled within a short time after the request to lock NWt was 
made, this error will occur 

$05: Event queue overflow (EVQOVFL) 

More events (see Chapter 6) have occurred than have been handled. 
Possibly the event fence is set too high, and few events are being handled, 

$06: SOS stack overflow (STKOVFL) 

The SOS stack has been pushed to more than 256 bytes, and the data 
at the bottom of the stack have been overwritten. 

$07: Invalid control or status request (BADSYSCALL) 

The device system has detected an invalid control or status request. 

$08: Too many drivers (MCTOVFL) 

Too many device drivers have been created for SOS to keep track of. 
$09: Memory too small {MEM2SML) 

The Apple Ill's memory is too small for SOS to operate in; that is, less 
than128K bytes. 
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$0A; Buffer Control Block damaged (VCBERR) 

The file system's Buffer Control Block has been damaged due to a 
memory failure. 

$08: File Control Block damaged (FCBERR) 

The file system's File Control Block has been damaged due to a 
memory failure. 

$0C: Invalid allocation blocks (ALCERR) 

Allocation blocks are invalid. 

$0E: Pathname too long (TOOLONG) 

A pathname supplied or internally generated contains more than 256 
characters. This can result from concatenating a long prefix to a long 
filename. 

$0F: Invalid buffer number (BADBUFNUM) 

An internal buffer allocation request has supplied an invalid buffer 
number- 

$10: Invalid buffer size (BADBUFSIZ) 

An internal buffer allocation request has supplied an invalid buffer size. 

D.3 Bootstrap Errors 

If an error occurs during the bootstrap operation, an error message is 
displayed (in uppercase inverse characters) in the middle of the video 
screen, the speaker beeps, and the system hangs, Bootstrap errors are 
not SOS errors, as they occur before SOS has started running: for this 
reason, they are not numbered. Any bootstrap error is a fatal error: you 
must insert a proper boot diskette, then hold down the CONTROL key 
and press the RESET button to reboot. 
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The following errors can be produced during a bootstrap operation: 
DRIVER FILE NOT FOUND 

There is no file named SOS.DRIVER listed in the volume directory of the 
boot disk. SOS cannot operate without device drivers, and the drivers 
nnust be stored in a file with this name in the volume directory of the disk. 

DRIVER FILE TOO LARGE 

The SOS.DRIVER file is too large to fit into the system's memory atong 
with the interpreter. Use the System Configuration Program to remove 
some drivers Jrom this file. 

EMPTY DRIVER FILE 

The SOS.DRIVER file contains no device drivers. SOS requires at least 
one device driver, .CONSOLE, to operate. 

INCOMPATIBLE INTERPRETER 

The interpreter is either too large or specifies a loading location that 
conflicts with SOS, This error usually occurs when trying to load an older 
interpreter with a newer version of SOS. 

INTERPRETER FILE NOT FOUND 

There is no file named SOS.INTERP listed in the volume directory of the 
boot disk. SOS cannot operate without an interpreter, and the interpreter 
must be stored in a file with this name, in the volume directory of the disk. 

INVALID DRIVER FILE 

The SOS.DRIVER file is not in the proper format for a driver file. Wake 
sure that the file was created by the System Configuration Program or 
obtained from a valid Apple III boot disk. 

I/O ERROR 

The loader encountered an I/O error while trying to read the kernel, 
interpreter, or driver file from the disk in the Apple Ill's internal disk drive. 
Make sure the correct disk is properly inserted in that drive. 
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KERNEL FILE NOT FOUND 

No file named SOS. KERNEL is listed in the volume directory of the boot 
disk. The files SOS.KERNEL, SOS.INTERR and SOS.DRIVER must all be 
present in the volume directory of a disk to be booted, 

ROM ERROR: PLEASE NOTIFY YOUR DEALER 

Your Apple III contains an older version of the bootstrap ROM that is not 
supported by this version of SOS. Your Apple dealer should be able to 
replace the ROM at no cost. If you receive this message, please contact 
your dealer or nearest Apple Service Center. 

TOO MANY BLOCK DEVICES 

The SOS.DRIVER file contains too many device drivers for block devices. 
Use the System Configuration Program to remove some of the block 
device drivers from this file. 



TOO MANY DEVICES 

The SOS.DRIVER file, while small enough to fit into memory, contains 
too many device drivers for SOS to keep track of. Use the System 
Configuration Program to remove some drivers from this file. 
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Interpreters can load additional code modules. When you write an 
interpreter, you may want to make these code modules relocatable. 
This appendix describes the relocation information generated by the 
Apple III Pascal Assembler. 

Appendix E is derived from the Apple III Pascal Technical Reference 
Manual. Read that manual if you want more detailed information, 

Most of the information about assembly-language code files described 
in the Apple III Pascal Technical Reference Manual is addressed to Pascal 
programmers. However, if you want to use Pascal Assembler code files 
when you write an interpreter, you need to deal with only two genera) 
areas: the overall organization of the code file, and the data structures 
generated for various psuedo-opcodes by the Pascal Assembler. 

E. 1 Code File Organization 



An assembly-language code file consists of a segment dictionary and a 
code part, as shown in Figure E-1 : 
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segment 

block diciionary 



first and 
only code 
segment 



block 1 



block 2 



V 



9 



linker 
Inforniation 
(unused) 



Figure E-1. An Assembly-Language Code File 

The first block of a code file generated by ttie Pascal Assembler is in the 
standard format for block of a Pascal code file; this block is called the 
segment dictionary. The remaining blocks of the file constitute the code 
part of the code file, which is a single code segment in this kind of file. The 
code part is followed by linker information; in an assembly-language code 
file, this information is unused. 

Be especially careful in reading this section: words (two bytes of 
data) are used as well as bytes. Be sure you know which type 
each number refers to. 



134 SOS Relerence Manual 



E.2 The Segment Dictionary 



Since the code part is a single segment, most of the information in tlie 
segment dictionary is unused. Figure E-2 shows the information that is 
used. 



low adi^resses 
high byle low byle 



unused 


CODEADDR = 1 




(retaiive block number) 


(segmeni 1 ) 


CODELENG 


(in bytes) 





unused 



byle word 

byte 2 word i 

byie 4 word 2" 

byte 6 word 3 

byte 51 1 word 255 



high addresses 



Figure E-2. A Segment Dictionary 



Two 2-byte fields in this block are relevant when you whte a module 
loader The first starts at byte 4 and is the starting block number 
(relative to the beginning of the file) of the code generated by the Pascal 
Assembler; call this CODEADDR, because that is the field name in the 
Pascal declaration. The second starts at byte 6 and is the length, in bytes, 
of the code; call it CODELENG, for the same reason. 



Your loading routine should begin loading at the relative block number 
{usually 1) indicated by CODEADDR, and should load the number of 
bytes indicated by CODELENG. 
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E.3 The Code Part of a Code File 



Following the segment dictionary is the code part, which contains the 
procedure dictionary and the procedures themselves. This is 
diagrammed in Figure E-3. 



byte 
CODELENG -1 



/ 



byiel 



high addresses 
high byte low byte 



numtier of 
procedures = f\ 



segment 
number - 1 



poiriter to procedure 1 



pointer to procedure 2 



more pointers 



pointer to procedure n 



attribute 
table 



procedure 1 
(highest procedure) 



code 



attribute 
tabie 



code 



procedure n 

(lowest 
procedure) 



more procedures 



byte 

CODELENG -2 



attribute 
table 



procedure 2 



code 



byte0 



low addresses 



Figure E-3. The Code Part of a Code File 
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E.3. 1 The Procedure Dictionary 

The low byte of the last word of the precedure dictionary is at the address 
CODELENG-2; the structure grows down toward lower addresses, as 
shown in Figure E-3. To decipher the structure, look at the word whose 
location Is calculated by CODEADDR * 512 + CODELENG-2. The low 
byte should contain 1 . The high byte tells you the number of procedures 
in the code file. Each use of the psuedo-opcodes .PROC or ,FUNC 
increments this number. Below this word is a sequence of words that 
contain self-relative pointers to the last word of each procedure in the 
code file. 

A self-relative pointer contains the absolute distance, in bytes, between 
the low byte of the pointer and the low byte of the word to which it points. 
To find the address referred to by a self-relative pointer, subtract the value 
of the pointer from the address of its location. 

The number of a procedure is an index into the procedure dictionary; 
the nth word in the dictionary (counting down from higher addresses) 
contains a pointer to the top (high address) of the code of procedure 
number fj. As is not a valid procedure number, the 0th word of the 
dictionary is used to store a Pascal-specific descriptor (usually 1) and 
the number of procedures in the code file (as described above). 

E.3.2 Procedures 

Each procedure consists of two parts: the procedure code, and the 
procedure attribute table. The procedure code is contained in the lower 
portion of the procedure and grows upward toward the higher 
addresses, 

E.3.3 Assembly- Language Procedure 
Attribute Tables 

A precedure '8 attribute table provides information needed to execute 
the procedure. Procedure attribute tables are pointed to by entries 
tn the procedure dictionary of each code file. 
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The format of the attribute table of an assembly-language procedure 
is illustrated in Figure E-4. 

The other type of attribute table is described in the Apple II! Pascal 
Technical Reference Manual. 

high addresses 
high byte low byte 

RELOCSEG PROCEDURE 
NUMBER NUMBER -■ 

ENTER IC {poinler lo ^ 
startofprucedurecode) 



number o( poinlers (n) 



base- relative 
relocation table 
(n self-relative pointers) 



number of pointers {rn) 



segment-relative 
relocation table 
(m selt-relalive pointers) 



number of pointers (p) 



self-relative 
relocation table 
(p self-relative pointers) 



number of pointers (g) 



interpreter-relative 
relocation table 
(q sell-relative pointers) 



low addresses 



Figure E-4. An Assefnbly-Language Procedure Attribute Table 
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The highest word in the attribute table of an assembly-language 
procedure always has in its PROCEDURE NUMBER field, This0 
can be used as a flag to indicate to your loading routine that relocation 
references may need changing to agree with the other information 
in the attribute table. The RELOCSEG NUMBER field must contain 0. 

The second-highest word of the attribute table is the ENTER IC field; a 
self-relative pointer to the first executable instruction of the procedure. 
Following this are four relocation tables; from high address to low 
address, they are base-relative, segment-relative, procedure-relative, 
and interpreter-relative. 

E.3.4 Relocation Tables 

A relocation table is a sequence of records that contain information 
necessary to relocate any relocatable addresses used by code within the 
procedure. These addresses must be relocated whenever the code file 
containing the procedure is loaded into or moved within memory. 

The format of all four relocation tables is the same: the highest word 
of each table specifies the number of entries [possibly 0) that follow 
at the lower addresses in the table. The remainder of each table contains 
the one-word self-relative pointers to locations in the procedure code 
that must be changed by the addition of the appropriate relative 
relocation constant, which is known to your interpreter when the code 
is loaded, 

E.3.4.1 Base-Relative Relocation Table 

Every reference to a label associated with the psuedo-opcodes 
.PUBLIC and .PRIVATE generates an entry into this table. In the Pascal 
environment, these opcodes flag references to data global to the Pascal 
program. 
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E.3.4.2 Segment-Relative Relocation Table 

References to labels associated with ,REF generate segment- relative 
relocation entries. The offsets in this table are relative to the beginning 
of the code portion of the code file: the address of the lowest byte of 
the code module is added to each of the addresses pointed to in the 
relocation table. Additionally, references to PROC or.FUNC names 
generate entries into this table. 

E.3.4.3 Procedure-Relative Relocation Table 

Addresses pointed to by the procedure-relative relocation table must 
be relocated relative to the lowest address of the procedure. The address 
of the lowest byte in the procedure must be added to the contents of 
the words pointed to in the relocation table. The relevant Assembler 
directives are .BYTE, .WORD, .BLOCK, and ASCII. Additionally, any 
non-relative reference (that is, JMP or LDA, but not BNE or BCS) 
generates an entry into this table. 

E.3.4.4 Interpreter-Relative Relocation Table 



Entnes into this table are generated by references to labels defined 

by the .INTERP psuedo-opcode. The Pascal System uses this to index ^ 

into a jump table in the interpreter 
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order of event queue 1 09 
organization, code file [132] 
OUTOFMEM [56] 
output device 40 
overviewof the Apple HI 3-a 
OVRERR [54] 

P 

page(s) 23, [31], [78], [81], [831 

pari of segment address 25 
paranneter(s) 

format of a name 159 

input [116] 

list, 

optional 152-154. [x] 
required 129, 150-152, [x] 

name 159-160 

passing 145 

pointer 145 



parent_entry_ length 85 
parent enlry number 85 
parent pointer 85 
parm count [xi] 
parmjist 149 
Pascal 118,143.(132] 

and BASIC modules 145 

assembler 145, [134] 

interpreter 145 

prefix 62 

program 145 

versus SOS prefixes 62 
path(s} 

access 52 
information 64-66 
multiple 52 

maximum number of 56 
pathname [3], [7], [9], [11], [17], 

[25], (291 
pathname 52, 59-61 

full 62 

partial 61-62 

syntax 60 

valid 61 
PERFORM 145 
period 42. 56 
peripheral device 8,104 
physical device 40, 54 

correspondence with logical 
devices 54 
PNFERR [54] 
point, decimal xix 
p0!nter(s) 31,69,152 

address extension 154-159 

byte order of 79 

comparing two 37 

direct 154,155-156 
to current 156 
toX-bank 155 

extended 123 

fields 79 

incrementing a 36-37 
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indirect 154, 156-159 

manipulation 36-38 

parameters 145 

preceding -block 78 

self- relative [136], [138] 

thiree-byte 98 
POSNERR [55] 
prefix (es) 60,61-62 

Pascal 62 

restrictions on 62 

SOS 62 
versus Pascal 62 
.PRINTER [111] 
printers 40 
priority of zero 108 
priority-queue scheme 108 
.PRIVATE [138] 
.PROC [136]. [139] 
procedure(s) [135], [136] 

attribute table [136] 

code [136] 

dictionary [135] 
entries [136] 
PROCEDURE NUMBER [138] 
procedure-relative relocation 

table [139] 
processing an event 106 
Processor, Apple III xvii 
Product Support Department 45 
program 

execution, restrictions on 14 

exiting from 66 
programming 

assembly-language xiii 

restrictions, circumvention of 
SOS 3 
psuedo-opcode(s) [136] 

FUNC [136] 

.PRIVATE [138] 

.PROC [136] 

.PUBLIC [138] 
PUBLIC [138] 



Q 

queuing an event 106 
R 

range, X-byte 15 
READ 67. 68, 71, [35-361 
read and write operations, 

sequential 50 
read -enable bit [12], [18] 
reading a directory file 91 
ref_num 52, 64 , 67, [2] , [29] , [33] , 

[35], [37], [39], [49] 

[41], [43], [45], [47] 
references, relocation [138] 
regions 

invalid 15, 16 

risky 15,16 
release memory 25 
RELEASE_SEG 27, [87] 
relocation 146 

constant [138] 

information 145 

references [138] 

table(s) [138] 

base-relative [138] 

interpreter- relative [139] 

procedure- relative [139[ 

segment-relative [139] 
RELOCSEG NUMBER [138] 
RENAME 69,90, [9-10] 
reqaccess [30] 
request_ count [35], [37] 
REQUEST_SEG 25, 121. [75-76] 

call 30 
required parameter list 129, 

150-152, [X] 

example 129 
resource manager 2-3 

defined 2 
resources 112-114 
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restrictions 

addressing 15 

bank-switching 28 

on program execution 14 
result 69,151 
return to interpreter 29 
risky regions 15,16 

addresses 32 

avotding 37 

warning 32 
ROM ERROR; PLEASE NOTIFY 

YOUR DEALER {130] 
root of file system 59 
,RS232 [111] 

S 

S-bank 11,23,28 

address 12,38 
in segment notation 25 

locations, direct pointers to 155 

nnemory 19 
sample programs, examples xiv 
sapling file 93. 95 

entry 89 

structure of a 96 
SBC 31 

scheme, priority-queue 108 
SCR 43 
screen 40 
searchmode [77] 
sectors 77 
seedling file 93, 95 

entry 89 

structure of a 95 
segaddress [85] 
seg_id [75], [78], [83] 
seg num [76], [78], [81], [83], 

[85], [87] 
segment 23-24 

address 24, 38 
bank part of 25 
conversion 33-35 



notation 23-27 

page part of 25 
allocated from free memory 29 
dictionary [132], [134] 
memory 7 

of memory, allocating a 121 
to bank-switched address 

conversion 33 
to extended address conversion 

33 

segment-relative relocation 

table [139] 
SEGNOTFND [88] 
SEGRODN [88] 
SEGTBLFULL [88] 
sequential 

access 51 
devices 7 

read and write operations 50 
serial printer {.PRINTER) [111] 
SET_EOF 66, 68, 72-73, [47-48] 
SET_FENCE 107, 110, 114, [91] 
SET_FILE_INFO 63, 68, 70, 88. 

90, 152, [11-16] 
SET_LEVEL 66,73, [51] 
SET_MARK 66, 68, 72, [43-44] 
SET_PREFIX 70, [25-26] 
SET_TIME 90, 112, 115, [95-96] 
slash (/) 56, 60 
slot number 44 

change 46 

of zero 44 
slot jTum 44, [68] 
software, common foundation 

for 2, 3 
Sophisticated Operating System 

See SOS 
SOS xvii,3,5-6, 16, 104 

1.1 xix, [106] 

1.2 18,77.81,82,84,85,88,92, 
93, 95, 99, 105 

1.3 xix, [106] 
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bank ll 
call(s) 8 
block [103] 
form error 160 

reporting 160-161 
form of 148-154.160 
types of M8 
device 
driver 
environment 20-21 
memory placement 21 
system 43 
disk request 55 
errors 
fatal [124], [126] 
general [124] 
non-fatal [124] 
fife system 56, 58 
future versions of 91 , 92. 93 
implementation 76 
interface 76 
Kernel 19 
environment 19-20 
memory placement 20 
macro 126 

for SOS call block 126 
prefix(es) 62 

versus Pascal 62 
programming restrictions, 

circumvention of 3 
specifications [105-111] 
support for 76 
system 104 
versions xix, [106] 
SOS.DRIVER 6,41 
SOS.INTERP 118 
SOS.KERNEL 6,41 
Sparse file{s) 63,94,97-98 
block allocation for 98 
copying 98 
special symbols xv 
STA 31 



Stack 17 20 

interpreter's 145 

overflow [127] 

pages 19 
stand-alone interpreter 118 
standard device drivers [109-111] 
standard file(s) 57-58 

locating a byte in 98-99 

storage formats of 92-99 
state of the macfiine, storing 

the 110 
status request 

$00, block device [60] 

$01, character device [60] 

$02, character device [61] 
status_code [59} 
status_list [60] 
STKOVFL [127] 
stop symbol xv 
storage formats 

directory headers 76 

entries 76 

of standard files 92-99 
storage type 64, 80, 83, 87 89, 

92. 95" 96, 97 [5], [19] 
sthng buffer [117]. [118] 
structure(s) 

hierarchical tree 56, 76 

logical 76 

of a sapling file 96 

of a seedling file 95 

of a tree file 96 

of an interpreter 119-121 

of block files 50-51 

of character files 50-51 
sub type 44, 45. [69] 
subdirectory (subdirectories) 8 

file(s) 57 78 
entry 89 

header 82, 83, 89 
subindex block 94. 96 
subroutine addressing 27-29 
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summary 

of address storage 38 

of interrupts and events 1 1 2 
switchable bank 11 

highest 15, 18 
symbol (s) 

eye xix 

hand xix 

stop xix 

u1.2 xix 
syntax 

device name 42 

file name 59 

pathname 60 

volume name 56 
System Configuration Program 

(SCP) 41,46 
system 

clock 112 

conftguration time 104 
file level 66 
operating 2-3 

statusduringevent handling 111 

T 

table 

procedure attribute [ 1 36] 
within interpreter 29, 30 
Technical Support Department 
146 

TERMINATE 114,115,126.131. 

[xi].[103] 

call, coding 131 

closing files before [103] 
termination character 67. [61], 

[64] 
three-byte 

address 13 

pointer 98 



time 
date and 
creation 64, 81 . 84, 88, 89-90 
format 90 

1ast_mod 64, 88, 89-90, [14], 
[19] 

time pointer [95], [97] 
time-dependent code 104 
timing loop 19,104 
TOO MANY BLOCK DEVICES 
[130] 

TOO MANY DEVICES [130] 
TOOLONG [128] 
top-level files 57 
total^blocks 45. 82, [23], [70] 
tracks 77 
transfer control 28 
transfercount [36] 
tree file 94. 96-97 

entry 89 

growing a 92-95 

structure of a 96 
tree structure, hierarchical 56 
tree, file system 61 
TYPERR [55] 

u 

unit number 44 
unit_num 44, [68] 
unsupported storage type 

(TYPERR) [55] 
utilities disk 41 
utility 

call(s) 114 

errors 160, [126] 
management 5 

y 

v1 .2 symbol xix 

and other versions xix 
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valid 

jumps 29 

pathnames 61 
value 69,151 
value/result parameter 152 
VCBERR 1128] 
version 81,84,88 

number 45 
version num 45, |70] 
VNFERR [54] 
vot name 60, [23] 
VOLUME 70, [23-24] 
volume(s) 53-54, 76 

bitmap 77,93 

blocks on a 77 

directorY 54, 57, 78, 93 
file 77 

header 79, 80, 89 
formats 77 
multiple 54 
name(s) 42, 55-56, 60 

advantages of 56 

syntax 56 
switching 54-55 
volume/device correspondence 
54 

w 

warning 

address conversion 1 23 
interface versus implementation 
99 

on accessing zero page and 

stack 1 7 
on pointer conversions 155 
on sample interpreter 125 
pointer 

direct 1 56 

indirect 158, 159 
risky regions 32 
termination 114 
unallocated memory 121 



WORD [1391 
words [133] 

WRITE 68,71,90. [37-38] 
write-enablebit [12], [18] 

X 

X register 14 

X-bank, direct pointers to 155 
X-byfe 14,15,31.145 

between $80 and $8F, indirect 
pointers with an 158 

format 14 

of $00, indirect pointers with 

an 157 
of$8F 16 
range 15 
X-page 145 

Y 

Y-register 15,32 
Z 

zero 

interpreter's 19 
page 15,17.20.29 
and stack 17 20 

warning on accessing 1 7 
conflicts with 16 
phorityof 108 
zero- page addressing mode 29 
zero-page indexed addressing 
mode 29 

Special Symbols and Numbers 

&V1.2 81.82,84 
$ xviii, xix 
$0 16 
$8F 16 
6502 xvii 

instruction set 8 



